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
     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 CONFIG_H
    21 #define CONFIG_H
    22 
    23 #include "ptr.h"
    24 #include <string>
    25 #include <vector>
    26 
    27 namespace ns3 {
    28 
    29 class AttributeValue;
    30 class Object;
    31 class CallbackBase;
    32 
    33 /**
    34  * \brief Configuration of simulation parameters and tracing
    35  * \ingroup core
    36  */
    37 namespace Config {
    38 
    39 /**
    40  * \param path a path to match attributes.
    41  * \param value the value to set in all matching attributes.
    42  *
    43  * This function will attempt to find attributes which
    44  * match the input path and will then set their value to the input
    45  * value.
    46  */
    47 void Set (std::string path, const AttributeValue &value);
    48 /**
    49  * \param name the full name of the attribute
    50  * \param value the value to set.
    51  *
    52  * This method overrides the initial value of the 
    53  * matching attribute. This method cannot fail: it will
    54  * crash if the input attribute name or value is invalid.
    55  */
    56 void SetDefault (std::string name, const AttributeValue &value);
    57 /**
    58  * \param name the full name of the attribute
    59  * \param value the value to set.
    60  * \returns true if the value was set successfully, false otherwise.
    61  *
    62  * This method overrides the initial value of the 
    63  * matching attribute. 
    64  */
    65 bool SetDefaultFailSafe (std::string name, const AttributeValue &value);
    66 /**
    67  * \param name the name of the requested GlobalValue.
    68  * \param value the value to set
    69  *
    70  * This method is equivalent to GlobalValue::Bind
    71  */
    72 void SetGlobal (std::string name, const AttributeValue &value);
    73 /**
    74  * \param name the name of the requested GlobalValue.
    75  * \param value the value to set
    76  *
    77  * This method is equivalent to GlobalValue::BindFailSafe
    78  */
    79 bool SetGlobalFailSafe (std::string name, const AttributeValue &value);
    80 /**
    81  * \param path a path to match trace sources.
    82  * \param cb the callback to connect to the matching trace sources.
    83  *
    84  * This function will attempt to find all trace sources which
    85  * match the input path and will then connect the input callback
    86  * to them.
    87  */
    88 void ConnectWithoutContext (std::string path, const CallbackBase &cb);
    89 /**
    90  * \param path a path to match trace sources.
    91  * \param cb the callback to disconnect to the matching trace sources.
    92  *
    93  * This function undoes the work of Config::Connect.
    94  */
    95 void DisconnectWithoutContext (std::string path, const CallbackBase &cb);
    96 /**
    97  * \param path a path to match trace sources.
    98  * \param cb the callback to connect to the matching trace sources.
    99  *
   100  * This function will attempt to find all trace sources which
   101  * match the input path and will then connect the input callback
   102  * to them in such a way that the callback will receive an extra
   103  * context string upon trace event notification.
   104  */
   105 void Connect (std::string path, const CallbackBase &cb);
   106 /**
   107  * \param path a path to match trace sources.
   108  * \param cb the callback to connect to the matching trace sources.
   109  *
   110  * This function undoes the work of Config::ConnectWithContext.
   111  */
   112 void Disconnect (std::string path, const CallbackBase &cb);
   113 
   114 /**
   115  * \brief hold a set of objects which match a specific search string.
   116  *
   117  * This class also allows you to perform a set of configuration operations
   118  * on the set of matching objects stored in the container. Specifically,
   119  * it is possible to perform bulk Connects and Sets.
   120  */
   121 class MatchContainer
   122 {
   123 public:
   124   typedef std::vector<Ptr<Object> >::const_iterator Iterator;
   125   MatchContainer ();
   126   // constructor used only by implementation.
   127   MatchContainer (const std::vector<Ptr<Object> > &objects, 
   128                   const std::vector<std::string> &contexts, 
   129                   std::string path);
   130 
   131   /**
   132    * \returns an iterator which points to the first item in the container
   133    */
   134   MatchContainer::Iterator Begin (void) const;
   135   /**
   136    * \returns an iterator which points to the last item in the container
   137    */
   138   MatchContainer::Iterator End (void) const;
   139   /**
   140    * \returns the number of items in the container
   141    */
   142   uint32_t GetN (void) const;
   143   /**
   144    * \param i index of item to lookup ([0,n[)
   145    * \returns the item requested.
   146    */
   147   Ptr<Object> Get (uint32_t i) const;
   148   /**
   149    * \param i index of item to lookup ([0,n[)
   150    * \returns the fully-qualified matching path associated
   151    *          to the requested item.
   152    *
   153    * The matching patch uniquely identifies the requested object.
   154    */
   155   std::string GetMatchedPath (uint32_t i) const;
   156   /**
   157    * \returns the path used to perform the object matching.
   158    */
   159   std::string GetPath (void) const;
   160 
   161   /**
   162    * \param name name of attribute to set
   163    * \param value value to set to the attribute
   164    *
   165    * Set the specified attribute value to all the objects stored in this
   166    * container.
   167    * \sa ns3::Config::Set
   168    */
   169   void Set (std::string name, const AttributeValue &value);
   170   /**
   171    * \param name the name of the trace source to connect to
   172    * \param cb the sink to connect to the trace source
   173    *
   174    * Connect the specified sink to all the objects stored in this
   175    * container.
   176    * \sa ns3::Config::Connect
   177    */
   178   void Connect (std::string name, const CallbackBase &cb);
   179   /**
   180    * \param name the name of the trace source to connect to
   181    * \param cb the sink to connect to the trace source
   182    *
   183    * Connect the specified sink to all the objects stored in this
   184    * container.
   185    * \sa ns3::Config::ConnectWithoutContext     
   186    */
   187   void ConnectWithoutContext (std::string name, const CallbackBase &cb);
   188   /**
   189    * \param name the name of the trace source to disconnect from
   190    * \param cb the sink to disconnect from the trace source
   191    *
   192    * Disconnect the specified sink from all the objects stored in this
   193    * container.
   194    * \sa ns3::Config::Disconnect
   195    */
   196   void Disconnect (std::string name, const CallbackBase &cb);
   197   /**
   198    * \param name the name of the trace source to disconnect from
   199    * \param cb the sink to disconnect from the trace source
   200    *
   201    * Disconnect the specified sink from all the objects stored in this
   202    * container.
   203    * \sa ns3::Config::DisconnectWithoutContext
   204    */
   205   void DisconnectWithoutContext (std::string name, const CallbackBase &cb);
   206 private:
   207   std::vector<Ptr<Object> > m_objects;
   208   std::vector<std::string> m_contexts;
   209   std::string m_path;
   210 };
   211 
   212 /**
   213  * \param path the path to perform a match against
   214  * \returns a container which contains all the objects which match the input
   215  *          path.
   216  */
   217 MatchContainer LookupMatches (std::string path);
   218 
   219 /**
   220  * \param obj a new root object
   221  *
   222  * Each root object is used during path matching as
   223  * the root of the path by Config::Connect, and Config::Set.
   224  */
   225 void RegisterRootNamespaceObject (Ptr<Object> obj);
   226 /**
   227  * \param obj a new root object
   228  *
   229  * This function undoes the work of Config::RegisterRootNamespaceObject.
   230  */
   231 void UnregisterRootNamespaceObject (Ptr<Object> obj);
   232 
   233 /**
   234  * \returns the number of registered root namespace objects.
   235  */
   236 uint32_t GetRootNamespaceObjectN (void);
   237 
   238 /**
   239  * \param i the index of the requested object.
   240  * \returns the requested root namespace object
   241  */
   242 Ptr<Object> GetRootNamespaceObject (uint32_t i);
   243 
   244 } // namespace Config
   245 
   246 } // namespace ns3
   247 
   248 #endif /* CONFIG_H */