src/core/config.h
author Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Sat, 04 Jul 2009 08:15:48 +0200
changeset 4654 2eaebe77d66b
parent 3787 985324e2caaa
permissions -rw-r--r--
Added tag ns-3.5 for changeset c975274c9707
mathieu@2586
     1
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
mathieu@2586
     2
/*
mathieu@2586
     3
 * Copyright (c) 2008 INRIA
mathieu@2586
     4
 *
mathieu@2586
     5
 * This program is free software; you can redistribute it and/or modify
mathieu@2586
     6
 * it under the terms of the GNU General Public License version 2 as
mathieu@2586
     7
 * published by the Free Software Foundation;
mathieu@2586
     8
 *
mathieu@2586
     9
 * This program is distributed in the hope that it will be useful,
mathieu@2586
    10
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
mathieu@2586
    11
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
mathieu@2586
    12
 * GNU General Public License for more details.
mathieu@2586
    13
 *
mathieu@2586
    14
 * You should have received a copy of the GNU General Public License
mathieu@2586
    15
 * along with this program; if not, write to the Free Software
mathieu@2586
    16
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
mathieu@2586
    17
 *
mathieu@2586
    18
 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
mathieu@2586
    19
 */
mathieu@3763
    20
#ifndef CONFIG_H
mathieu@3763
    21
#define CONFIG_H
mathieu@2474
    22
mathieu@2474
    23
#include "ptr.h"
mathieu@2474
    24
#include <string>
mathieu@3787
    25
#include <vector>
mathieu@2474
    26
mathieu@2474
    27
namespace ns3 {
mathieu@2474
    28
mathieu@2965
    29
class AttributeValue;
mathieu@2965
    30
class Object;
mathieu@2965
    31
class CallbackBase;
mathieu@2965
    32
mathieu@3190
    33
/**
mathieu@3190
    34
 * \brief Configuration of simulation parameters and tracing
mathieu@3190
    35
 * \ingroup core
mathieu@3190
    36
 */
mathieu@2474
    37
namespace Config {
mathieu@2474
    38
mathieu@2585
    39
/**
mathieu@2585
    40
 * \param path a path to match attributes.
mathieu@2585
    41
 * \param value the value to set in all matching attributes.
mathieu@2585
    42
 *
mathieu@2585
    43
 * This function will attempt to find attributes which
mathieu@2585
    44
 * match the input path and will then set their value to the input
mathieu@2585
    45
 * value.
mathieu@2585
    46
 */
mathieu@2965
    47
void Set (std::string path, const AttributeValue &value);
mathieu@2585
    48
/**
mathieu@2585
    49
 * \param name the full name of the attribute
mathieu@2585
    50
 * \param value the value to set.
mathieu@2585
    51
 *
mathieu@2585
    52
 * This method overrides the initial value of the 
mathieu@2585
    53
 * matching attribute. This method cannot fail: it will
mathieu@2585
    54
 * crash if the input attribute name or value is invalid.
mathieu@2585
    55
 */
mathieu@2965
    56
void SetDefault (std::string name, const AttributeValue &value);
mathieu@2585
    57
/**
mathieu@2585
    58
 * \param name the full name of the attribute
mathieu@2585
    59
 * \param value the value to set.
mathieu@2585
    60
 * \returns true if the value was set successfully, false otherwise.
mathieu@2585
    61
 *
mathieu@2585
    62
 * This method overrides the initial value of the 
mathieu@2585
    63
 * matching attribute. 
mathieu@2585
    64
 */
mathieu@2965
    65
bool SetDefaultFailSafe (std::string name, const AttributeValue &value);
mathieu@2585
    66
/**
mathieu@2585
    67
 * \param name the name of the requested GlobalValue.
mathieu@2585
    68
 * \param value the value to set
mathieu@2585
    69
 *
mathieu@2585
    70
 * This method is equivalent to GlobalValue::Bind
mathieu@2585
    71
 */
mathieu@2965
    72
void SetGlobal (std::string name, const AttributeValue &value);
mathieu@2585
    73
/**
mathieu@2585
    74
 * \param name the name of the requested GlobalValue.
mathieu@2585
    75
 * \param value the value to set
mathieu@2585
    76
 *
mathieu@2585
    77
 * This method is equivalent to GlobalValue::BindFailSafe
mathieu@2585
    78
 */
mathieu@2965
    79
bool SetGlobalFailSafe (std::string name, const AttributeValue &value);
mathieu@2585
    80
/**
mathieu@2585
    81
 * \param path a path to match trace sources.
mathieu@2585
    82
 * \param cb the callback to connect to the matching trace sources.
mathieu@2585
    83
 *
mathieu@2585
    84
 * This function will attempt to find all trace sources which
mathieu@2585
    85
 * match the input path and will then connect the input callback
mathieu@2585
    86
 * to them.
mathieu@2585
    87
 */
mathieu@2594
    88
void ConnectWithoutContext (std::string path, const CallbackBase &cb);
mathieu@2585
    89
/**
mathieu@2585
    90
 * \param path a path to match trace sources.
mathieu@2585
    91
 * \param cb the callback to disconnect to the matching trace sources.
mathieu@2585
    92
 *
mathieu@2585
    93
 * This function undoes the work of Config::Connect.
mathieu@2585
    94
 */
mathieu@2594
    95
void DisconnectWithoutContext (std::string path, const CallbackBase &cb);
mathieu@2585
    96
/**
mathieu@2585
    97
 * \param path a path to match trace sources.
mathieu@2585
    98
 * \param cb the callback to connect to the matching trace sources.
mathieu@2585
    99
 *
mathieu@2585
   100
 * This function will attempt to find all trace sources which
mathieu@2585
   101
 * match the input path and will then connect the input callback
mathieu@2585
   102
 * to them in such a way that the callback will receive an extra
mathieu@2585
   103
 * context string upon trace event notification.
mathieu@2585
   104
 */
mathieu@2594
   105
void Connect (std::string path, const CallbackBase &cb);
mathieu@2585
   106
/**
mathieu@2585
   107
 * \param path a path to match trace sources.
mathieu@2585
   108
 * \param cb the callback to connect to the matching trace sources.
mathieu@2585
   109
 *
mathieu@2585
   110
 * This function undoes the work of Config::ConnectWithContext.
mathieu@2585
   111
 */
mathieu@2594
   112
void Disconnect (std::string path, const CallbackBase &cb);
mathieu@2474
   113
mathieu@3999
   114
/**
mathieu@3999
   115
 * \brief hold a set of objects which match a specific search string.
mathieu@3999
   116
 *
mathieu@3999
   117
 * This class also allows you to perform a set of configuration operations
mathieu@3999
   118
 * on the set of matching objects stored in the container. Specifically,
mathieu@3999
   119
 * it is possible to perform bulk Connects and Sets.
mathieu@3999
   120
 */
mathieu@3787
   121
class MatchContainer
mathieu@3787
   122
{
mathieu@3787
   123
public:
mathieu@3787
   124
  typedef std::vector<Ptr<Object> >::const_iterator Iterator;
mathieu@3787
   125
  MatchContainer ();
mathieu@3999
   126
  // constructor used only by implementation.
mathieu@3787
   127
  MatchContainer (const std::vector<Ptr<Object> > &objects, 
mathieu@3787
   128
                  const std::vector<std::string> &contexts, 
mathieu@3787
   129
                  std::string path);
mathieu@3787
   130
mathieu@3999
   131
  /**
mathieu@3999
   132
   * \returns an iterator which points to the first item in the container
mathieu@3999
   133
   */
mathieu@3787
   134
  MatchContainer::Iterator Begin (void) const;
mathieu@3999
   135
  /**
mathieu@3999
   136
   * \returns an iterator which points to the last item in the container
mathieu@3999
   137
   */
mathieu@3787
   138
  MatchContainer::Iterator End (void) const;
mathieu@3999
   139
  /**
mathieu@3999
   140
   * \returns the number of items in the container
mathieu@3999
   141
   */
mathieu@3787
   142
  uint32_t GetN (void) const;
mathieu@3999
   143
  /**
mathieu@3999
   144
   * \param i index of item to lookup ([0,n[)
mathieu@3999
   145
   * \returns the item requested.
mathieu@3999
   146
   */
mathieu@3787
   147
  Ptr<Object> Get (uint32_t i) const;
mathieu@3999
   148
  /**
mathieu@3999
   149
   * \param i index of item to lookup ([0,n[)
mathieu@3999
   150
   * \returns the fully-qualified matching path associated
mathieu@3999
   151
   *          to the requested item.
mathieu@3999
   152
   *
mathieu@3999
   153
   * The matching patch uniquely identifies the requested object.
mathieu@3999
   154
   */
mathieu@3787
   155
  std::string GetMatchedPath (uint32_t i) const;
mathieu@3999
   156
  /**
mathieu@3999
   157
   * \returns the path used to perform the object matching.
mathieu@3999
   158
   */
mathieu@3787
   159
  std::string GetPath (void) const;
mathieu@3787
   160
mathieu@3999
   161
  /**
mathieu@3999
   162
   * \param name name of attribute to set
mathieu@3999
   163
   * \param value value to set to the attribute
mathieu@3999
   164
   *
mathieu@3999
   165
   * Set the specified attribute value to all the objects stored in this
mathieu@3999
   166
   * container.
mathieu@3999
   167
   * \sa ns3::Config::Set
mathieu@3999
   168
   */
mathieu@3787
   169
  void Set (std::string name, const AttributeValue &value);
mathieu@3999
   170
  /**
mathieu@3999
   171
   * \param name the name of the trace source to connect to
mathieu@3999
   172
   * \param cb the sink to connect to the trace source
mathieu@3999
   173
   *
mathieu@3999
   174
   * Connect the specified sink to all the objects stored in this
mathieu@3999
   175
   * container.
mathieu@3999
   176
   * \sa ns3::Config::Connect
mathieu@3999
   177
   */
mathieu@3787
   178
  void Connect (std::string name, const CallbackBase &cb);
mathieu@3999
   179
  /**
mathieu@3999
   180
   * \param name the name of the trace source to connect to
mathieu@3999
   181
   * \param cb the sink to connect to the trace source
mathieu@3999
   182
   *
mathieu@3999
   183
   * Connect the specified sink to all the objects stored in this
mathieu@3999
   184
   * container.
mathieu@3999
   185
   * \sa ns3::Config::ConnectWithoutContext     
mathieu@3999
   186
   */
mathieu@3787
   187
  void ConnectWithoutContext (std::string name, const CallbackBase &cb);
mathieu@3999
   188
  /**
mathieu@3999
   189
   * \param name the name of the trace source to disconnect from
mathieu@3999
   190
   * \param cb the sink to disconnect from the trace source
mathieu@3999
   191
   *
mathieu@3999
   192
   * Disconnect the specified sink from all the objects stored in this
mathieu@3999
   193
   * container.
mathieu@3999
   194
   * \sa ns3::Config::Disconnect
mathieu@3999
   195
   */
mathieu@3787
   196
  void Disconnect (std::string name, const CallbackBase &cb);
mathieu@3999
   197
  /**
mathieu@3999
   198
   * \param name the name of the trace source to disconnect from
mathieu@3999
   199
   * \param cb the sink to disconnect from the trace source
mathieu@3999
   200
   *
mathieu@3999
   201
   * Disconnect the specified sink from all the objects stored in this
mathieu@3999
   202
   * container.
mathieu@3999
   203
   * \sa ns3::Config::DisconnectWithoutContext
mathieu@3999
   204
   */
mathieu@3787
   205
  void DisconnectWithoutContext (std::string name, const CallbackBase &cb);
mathieu@3787
   206
private:
mathieu@3787
   207
  std::vector<Ptr<Object> > m_objects;
mathieu@3787
   208
  std::vector<std::string> m_contexts;
mathieu@3787
   209
  std::string m_path;
mathieu@3787
   210
};
mathieu@3787
   211
mathieu@3999
   212
/**
mathieu@3999
   213
 * \param path the path to perform a match against
mathieu@3999
   214
 * \returns a container which contains all the objects which match the input
mathieu@3999
   215
 *          path.
mathieu@3999
   216
 */
mathieu@3787
   217
MatchContainer LookupMatches (std::string path);
mathieu@3787
   218
mathieu@2585
   219
/**
mathieu@2585
   220
 * \param obj a new root object
mathieu@2585
   221
 *
mathieu@2585
   222
 * Each root object is used during path matching as
mathieu@2585
   223
 * the root of the path by Config::Connect, and Config::Set.
mathieu@2585
   224
 */
mathieu@2474
   225
void RegisterRootNamespaceObject (Ptr<Object> obj);
mathieu@2585
   226
/**
mathieu@2585
   227
 * \param obj a new root object
mathieu@2585
   228
 *
mathieu@2585
   229
 * This function undoes the work of Config::RegisterRootNamespaceObject.
mathieu@2585
   230
 */
mathieu@2532
   231
void UnregisterRootNamespaceObject (Ptr<Object> obj);
mathieu@2474
   232
mathieu@2941
   233
/**
mathieu@2941
   234
 * \returns the number of registered root namespace objects.
mathieu@2941
   235
 */
mathieu@2941
   236
uint32_t GetRootNamespaceObjectN (void);
mathieu@2941
   237
mathieu@2941
   238
/**
mathieu@2941
   239
 * \param i the index of the requested object.
mathieu@2941
   240
 * \returns the requested root namespace object
mathieu@2941
   241
 */
mathieu@2941
   242
Ptr<Object> GetRootNamespaceObject (uint32_t i);
mathieu@2941
   243
mathieu@2474
   244
} // namespace Config
mathieu@2474
   245
mathieu@2474
   246
} // namespace ns3
mathieu@2474
   247
mathieu@3763
   248
#endif /* CONFIG_H */