mathieu@2586: /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
mathieu@2586: /*
mathieu@2586:  * Copyright (c) 2008 INRIA
mathieu@2586:  *
mathieu@2586:  * This program is free software; you can redistribute it and/or modify
mathieu@2586:  * it under the terms of the GNU General Public License version 2 as
mathieu@2586:  * published by the Free Software Foundation;
mathieu@2586:  *
mathieu@2586:  * This program is distributed in the hope that it will be useful,
mathieu@2586:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
mathieu@2586:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
mathieu@2586:  * GNU General Public License for more details.
mathieu@2586:  *
mathieu@2586:  * You should have received a copy of the GNU General Public License
mathieu@2586:  * along with this program; if not, write to the Free Software
mathieu@2586:  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
mathieu@2586:  *
mathieu@2586:  * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
mathieu@2586:  */
mathieu@3763: #ifndef CONFIG_H
mathieu@3763: #define CONFIG_H
mathieu@2474: 
mathieu@2474: #include "ptr.h"
mathieu@2474: #include <string>
mathieu@3787: #include <vector>
mathieu@2474: 
mathieu@2474: namespace ns3 {
mathieu@2474: 
mathieu@2965: class AttributeValue;
mathieu@2965: class Object;
mathieu@2965: class CallbackBase;
mathieu@2965: 
mathieu@3190: /**
mathieu@3190:  * \brief Configuration of simulation parameters and tracing
mathieu@3190:  * \ingroup core
mathieu@3190:  */
mathieu@2474: namespace Config {
mathieu@2474: 
mathieu@2585: /**
mathieu@2585:  * \param path a path to match attributes.
mathieu@2585:  * \param value the value to set in all matching attributes.
mathieu@2585:  *
mathieu@2585:  * This function will attempt to find attributes which
mathieu@2585:  * match the input path and will then set their value to the input
mathieu@2585:  * value.
mathieu@2585:  */
mathieu@2965: void Set (std::string path, const AttributeValue &value);
mathieu@2585: /**
mathieu@2585:  * \param name the full name of the attribute
mathieu@2585:  * \param value the value to set.
mathieu@2585:  *
mathieu@2585:  * This method overrides the initial value of the 
mathieu@2585:  * matching attribute. This method cannot fail: it will
mathieu@2585:  * crash if the input attribute name or value is invalid.
mathieu@2585:  */
mathieu@2965: void SetDefault (std::string name, const AttributeValue &value);
mathieu@2585: /**
mathieu@2585:  * \param name the full name of the attribute
mathieu@2585:  * \param value the value to set.
mathieu@2585:  * \returns true if the value was set successfully, false otherwise.
mathieu@2585:  *
mathieu@2585:  * This method overrides the initial value of the 
mathieu@2585:  * matching attribute. 
mathieu@2585:  */
mathieu@2965: bool SetDefaultFailSafe (std::string name, const AttributeValue &value);
mathieu@2585: /**
mathieu@2585:  * \param name the name of the requested GlobalValue.
mathieu@2585:  * \param value the value to set
mathieu@2585:  *
mathieu@2585:  * This method is equivalent to GlobalValue::Bind
mathieu@2585:  */
mathieu@2965: void SetGlobal (std::string name, const AttributeValue &value);
mathieu@2585: /**
mathieu@2585:  * \param name the name of the requested GlobalValue.
mathieu@2585:  * \param value the value to set
mathieu@2585:  *
mathieu@2585:  * This method is equivalent to GlobalValue::BindFailSafe
mathieu@2585:  */
mathieu@2965: bool SetGlobalFailSafe (std::string name, const AttributeValue &value);
mathieu@2585: /**
mathieu@2585:  * \param path a path to match trace sources.
mathieu@2585:  * \param cb the callback to connect to the matching trace sources.
mathieu@2585:  *
mathieu@2585:  * This function will attempt to find all trace sources which
mathieu@2585:  * match the input path and will then connect the input callback
mathieu@2585:  * to them.
mathieu@2585:  */
mathieu@2594: void ConnectWithoutContext (std::string path, const CallbackBase &cb);
mathieu@2585: /**
mathieu@2585:  * \param path a path to match trace sources.
mathieu@2585:  * \param cb the callback to disconnect to the matching trace sources.
mathieu@2585:  *
mathieu@2585:  * This function undoes the work of Config::Connect.
mathieu@2585:  */
mathieu@2594: void DisconnectWithoutContext (std::string path, const CallbackBase &cb);
mathieu@2585: /**
mathieu@2585:  * \param path a path to match trace sources.
mathieu@2585:  * \param cb the callback to connect to the matching trace sources.
mathieu@2585:  *
mathieu@2585:  * This function will attempt to find all trace sources which
mathieu@2585:  * match the input path and will then connect the input callback
mathieu@2585:  * to them in such a way that the callback will receive an extra
mathieu@2585:  * context string upon trace event notification.
mathieu@2585:  */
mathieu@2594: void Connect (std::string path, const CallbackBase &cb);
mathieu@2585: /**
mathieu@2585:  * \param path a path to match trace sources.
mathieu@2585:  * \param cb the callback to connect to the matching trace sources.
mathieu@2585:  *
mathieu@2585:  * This function undoes the work of Config::ConnectWithContext.
mathieu@2585:  */
mathieu@2594: void Disconnect (std::string path, const CallbackBase &cb);
mathieu@2474: 
mathieu@3999: /**
mathieu@3999:  * \brief hold a set of objects which match a specific search string.
mathieu@3999:  *
mathieu@3999:  * This class also allows you to perform a set of configuration operations
mathieu@3999:  * on the set of matching objects stored in the container. Specifically,
mathieu@3999:  * it is possible to perform bulk Connects and Sets.
mathieu@3999:  */
mathieu@3787: class MatchContainer
mathieu@3787: {
mathieu@3787: public:
mathieu@3787:   typedef std::vector<Ptr<Object> >::const_iterator Iterator;
mathieu@3787:   MatchContainer ();
mathieu@3999:   // constructor used only by implementation.
mathieu@3787:   MatchContainer (const std::vector<Ptr<Object> > &objects, 
mathieu@3787:                   const std::vector<std::string> &contexts, 
mathieu@3787:                   std::string path);
mathieu@3787: 
mathieu@3999:   /**
mathieu@3999:    * \returns an iterator which points to the first item in the container
mathieu@3999:    */
mathieu@3787:   MatchContainer::Iterator Begin (void) const;
mathieu@3999:   /**
mathieu@3999:    * \returns an iterator which points to the last item in the container
mathieu@3999:    */
mathieu@3787:   MatchContainer::Iterator End (void) const;
mathieu@3999:   /**
mathieu@3999:    * \returns the number of items in the container
mathieu@3999:    */
mathieu@3787:   uint32_t GetN (void) const;
mathieu@3999:   /**
mathieu@3999:    * \param i index of item to lookup ([0,n[)
mathieu@3999:    * \returns the item requested.
mathieu@3999:    */
mathieu@3787:   Ptr<Object> Get (uint32_t i) const;
mathieu@3999:   /**
mathieu@3999:    * \param i index of item to lookup ([0,n[)
mathieu@3999:    * \returns the fully-qualified matching path associated
mathieu@3999:    *          to the requested item.
mathieu@3999:    *
mathieu@3999:    * The matching patch uniquely identifies the requested object.
mathieu@3999:    */
mathieu@3787:   std::string GetMatchedPath (uint32_t i) const;
mathieu@3999:   /**
mathieu@3999:    * \returns the path used to perform the object matching.
mathieu@3999:    */
mathieu@3787:   std::string GetPath (void) const;
mathieu@3787: 
mathieu@3999:   /**
mathieu@3999:    * \param name name of attribute to set
mathieu@3999:    * \param value value to set to the attribute
mathieu@3999:    *
mathieu@3999:    * Set the specified attribute value to all the objects stored in this
mathieu@3999:    * container.
mathieu@3999:    * \sa ns3::Config::Set
mathieu@3999:    */
mathieu@3787:   void Set (std::string name, const AttributeValue &value);
mathieu@3999:   /**
mathieu@3999:    * \param name the name of the trace source to connect to
mathieu@3999:    * \param cb the sink to connect to the trace source
mathieu@3999:    *
mathieu@3999:    * Connect the specified sink to all the objects stored in this
mathieu@3999:    * container.
mathieu@3999:    * \sa ns3::Config::Connect
mathieu@3999:    */
mathieu@3787:   void Connect (std::string name, const CallbackBase &cb);
mathieu@3999:   /**
mathieu@3999:    * \param name the name of the trace source to connect to
mathieu@3999:    * \param cb the sink to connect to the trace source
mathieu@3999:    *
mathieu@3999:    * Connect the specified sink to all the objects stored in this
mathieu@3999:    * container.
mathieu@3999:    * \sa ns3::Config::ConnectWithoutContext     
mathieu@3999:    */
mathieu@3787:   void ConnectWithoutContext (std::string name, const CallbackBase &cb);
mathieu@3999:   /**
mathieu@3999:    * \param name the name of the trace source to disconnect from
mathieu@3999:    * \param cb the sink to disconnect from the trace source
mathieu@3999:    *
mathieu@3999:    * Disconnect the specified sink from all the objects stored in this
mathieu@3999:    * container.
mathieu@3999:    * \sa ns3::Config::Disconnect
mathieu@3999:    */
mathieu@3787:   void Disconnect (std::string name, const CallbackBase &cb);
mathieu@3999:   /**
mathieu@3999:    * \param name the name of the trace source to disconnect from
mathieu@3999:    * \param cb the sink to disconnect from the trace source
mathieu@3999:    *
mathieu@3999:    * Disconnect the specified sink from all the objects stored in this
mathieu@3999:    * container.
mathieu@3999:    * \sa ns3::Config::DisconnectWithoutContext
mathieu@3999:    */
mathieu@3787:   void DisconnectWithoutContext (std::string name, const CallbackBase &cb);
mathieu@3787: private:
mathieu@3787:   std::vector<Ptr<Object> > m_objects;
mathieu@3787:   std::vector<std::string> m_contexts;
mathieu@3787:   std::string m_path;
mathieu@3787: };
mathieu@3787: 
mathieu@3999: /**
mathieu@3999:  * \param path the path to perform a match against
mathieu@3999:  * \returns a container which contains all the objects which match the input
mathieu@3999:  *          path.
mathieu@3999:  */
mathieu@3787: MatchContainer LookupMatches (std::string path);
mathieu@3787: 
mathieu@2585: /**
mathieu@2585:  * \param obj a new root object
mathieu@2585:  *
mathieu@2585:  * Each root object is used during path matching as
mathieu@2585:  * the root of the path by Config::Connect, and Config::Set.
mathieu@2585:  */
mathieu@2474: void RegisterRootNamespaceObject (Ptr<Object> obj);
mathieu@2585: /**
mathieu@2585:  * \param obj a new root object
mathieu@2585:  *
mathieu@2585:  * This function undoes the work of Config::RegisterRootNamespaceObject.
mathieu@2585:  */
mathieu@2532: void UnregisterRootNamespaceObject (Ptr<Object> obj);
mathieu@2474: 
mathieu@2941: /**
mathieu@2941:  * \returns the number of registered root namespace objects.
mathieu@2941:  */
mathieu@2941: uint32_t GetRootNamespaceObjectN (void);
mathieu@2941: 
mathieu@2941: /**
mathieu@2941:  * \param i the index of the requested object.
mathieu@2941:  * \returns the requested root namespace object
mathieu@2941:  */
mathieu@2941: Ptr<Object> GetRootNamespaceObject (uint32_t i);
mathieu@2941: 
mathieu@2474: } // namespace Config
mathieu@2474: 
mathieu@2474: } // namespace ns3
mathieu@2474: 
mathieu@3763: #endif /* CONFIG_H */