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 /** 28 * \file 29 * \ingroup config 30 * Declaration of the various ns3::Config functions and classes. 31 */ 32 33 namespace ns3 { 34 35 class AttributeValue; 36 class Object; 37 class CallbackBase; 38 39 /** 40 * \ingroup core 41 * \defgroup config Configuration 42 * \brief Configuration of simulation parameters and tracing. 43 */ 44 45 /** 46 * \ingroup config 47 * Namespace for the various functions implementing the Config system. 48 */ 49 namespace Config { 50 51 /** 52 * \ingroup config 53 * Reset the initial value of every attribute as well as the value of every 54 * global to what they were before any call to SetDefault and SetGlobal. 55 */ 56 void Reset (void); 57 58 /** 59 * \ingroup config 60 * \param [in] path A path to match attributes. 61 * \param [in] value The value to set in all matching attributes. 62 * 63 * This function will attempt to find attributes which 64 * match the input path and will then set their value to the input 65 * value. If no such attributes are found, the function will throw 66 * a fatal error; use SetFailSafe if the lack of a match is to be permitted. 67 */ 68 void Set (std::string path, const AttributeValue &value); 69 /** 70 * This function will attempt to find attributes which 71 * match the input path and will then set their value to the input 72 * value, and will return true if at least one such attribute is found. 73 * \return \c true if any matching attributes could be set. 74 */ 75 bool SetFailSafe (std::string path, const AttributeValue &value); 76 /** 77 * \ingroup config 78 * \param [in] name The full name of the attribute 79 * \param [in] value The value to set. 80 * 81 * This method overrides the initial value of the 82 * matching attribute. This method cannot fail: it will 83 * crash if the input attribute name or value is invalid. 84 */ 85 void SetDefault (std::string name, const AttributeValue &value); 86 /** 87 * \ingroup config 88 * \param [in] name The full name of the attribute 89 * \param [in] value The value to set. 90 * \returns \c true if the value was set successfully, false otherwise. 91 * 92 * This method overrides the initial value of the 93 * matching attribute. 94 */ 95 bool SetDefaultFailSafe (std::string name, const AttributeValue &value); 96 /** 97 * \ingroup config 98 * \param [in] name The name of the requested GlobalValue. 99 * \param [in] value The value to set 100 * 101 * This method is equivalent to GlobalValue::Bind 102 */ 103 void SetGlobal (std::string name, const AttributeValue &value); 104 /** 105 * \ingroup config 106 * \param [in] name The name of the requested GlobalValue. 107 * \param [in] value The value to set 108 * \return \c true if the GlobalValue could be set. 109 * 110 * This method is equivalent to GlobalValue::BindFailSafe 111 */ 112 bool SetGlobalFailSafe (std::string name, const AttributeValue &value); 113 /** 114 * \ingroup config 115 * \param [in] path A path to match trace sources. 116 * \param [in] cb The callback to connect to the matching trace sources. 117 * 118 * This function will attempt to find all trace sources which 119 * match the input path and will then connect the input callback 120 * to them. If no matching trace sources are found, this method will 121 * throw a fatal error. Use ConnectWithoutContextFailSafe if the absence 122 * of matching trace sources should not be fatal. 123 */ 124 void ConnectWithoutContext (std::string path, const CallbackBase &cb); 125 /** 126 * This function will attempt to find all trace sources which 127 * match the input path and will then connect the input callback 128 * to them. If no matching trace sources are found, this method will 129 * return false; otherwise true. 130 * \returns \c true if any trace sources could be connected. 131 */ 132 bool ConnectWithoutContextFailSafe (std::string path, const CallbackBase &cb); 133 /** 134 * \ingroup config 135 * \param [in] path A path to match trace sources. 136 * \param [in] cb The callback to disconnect to the matching trace sources. 137 * 138 * This function undoes the work of Config::Connect. 139 */ 140 void DisconnectWithoutContext (std::string path, const CallbackBase &cb); 141 /** 142 * \ingroup config 143 * \param [in] path A path to match trace sources. 144 * \param [in] cb The callback to connect to the matching trace sources. 145 * 146 * This function will attempt to find all trace sources which 147 * match the input path and will then connect the input callback 148 * to them in such a way that the callback will receive an extra 149 * context string upon trace event notification. 150 * If no matching trace sources are found, this method will 151 * throw a fatal error. Use ConnectFailSafe if the absence 152 * of matching trace sources should not be fatal. 153 */ 154 void Connect (std::string path, const CallbackBase &cb); 155 /** 156 * This function will attempt to find all trace sources which 157 * match the input path and will then connect the input callback 158 * to them in such a way that the callback will receive an extra 159 * context string upon trace event notification. 160 * \returns \c true if any trace sources could be connected. 161 */ 162 bool ConnectFailSafe (std::string path, const CallbackBase &cb); 163 /** 164 * \ingroup config 165 * \param [in] path A path to match trace sources. 166 * \param [in] cb The callback to connect to the matching trace sources. 167 * 168 * This function undoes the work of Config::ConnectWithContext. 169 */ 170 void Disconnect (std::string path, const CallbackBase &cb); 171 172 /** 173 * \ingroup config 174 * \brief hold a set of objects which match a specific search string. 175 * 176 * This class also allows you to perform a set of configuration operations 177 * on the set of matching objects stored in the container. Specifically, 178 * it is possible to perform bulk Connects and Sets. 179 */ 180 class MatchContainer 181 { 182 public: 183 /** Const iterator over the objects in this container. */ 184 typedef std::vector<Ptr<Object> >::const_iterator Iterator; 185 MatchContainer (); 186 /** 187 * Constructor used only by implementation. 188 * 189 * \param [in] objects The vector of objects to store in this container. 190 * \param [in] contexts The corresponding contexts. 191 * \param [in] path The path used for object matching. 192 */ 193 MatchContainer (const std::vector<Ptr<Object> > &objects, 194 const std::vector<std::string> &contexts, 195 std::string path); 196 197 /** 198 * \returns An iterator which points to the first item in the container 199 */ 200 MatchContainer::Iterator Begin (void) const; 201 /** 202 * \returns An iterator which points to the last item in the container 203 */ 204 MatchContainer::Iterator End (void) const; 205 /** 206 * \returns The number of items in the container 207 */ 208 std::size_t GetN (void) const; 209 /** 210 * \param [in] i Index of item to lookup ([0,n[) 211 * \returns The item requested. 212 */ 213 Ptr<Object> Get (std::size_t i) const; 214 /** 215 * \param [in] i Index of item to lookup ([0,n[) 216 * \returns The fully-qualified matching path associated 217 * to the requested item. 218 * 219 * The matching patch uniquely identifies the requested object. 220 */ 221 std::string GetMatchedPath (uint32_t i) const; 222 /** 223 * \returns The path used to perform the object matching. 224 */ 225 std::string GetPath (void) const; 226 227 /** 228 * \param [in] name Name of attribute to set 229 * \param [in] value Value to set to the attribute 230 * 231 * Set the specified attribute value to all the objects stored in this 232 * container. This method will raise a fatal error if no such attribute 233 * exists; use SetFailSafe if the absence of the attribute is to be 234 * permitted. 235 * \sa ns3::Config::Set 236 */ 237 void Set (std::string name, const AttributeValue &value); 238 /** 239 * Set the specified attribute value to all the objects stored in this 240 * container. This method will return true if any attributes could be 241 * set, and false otherwise. 242 * \returns \c true if any attributes could be set. 243 */ 244 bool SetFailSafe (std::string name, const AttributeValue &value); 245 /** 246 * \param [in] name The name of the trace source to connect to 247 * \param [in] cb The sink to connect to the trace source 248 * 249 * Connect the specified sink to all the objects stored in this 250 * container. This method will raise a fatal error if no objects could 251 * be connected; use ConnectFailSafe if no connections is a valid possible 252 * outcome. 253 * \sa ns3::Config::Connect 254 */ 255 void Connect (std::string name, const CallbackBase &cb); 256 /** 257 * Connect the specified sink to all the objects stored in this 258 * container. This method will return true if any trace sources could be 259 * connected, and false otherwise. 260 * \returns \c true if any trace sources could be connected. 261 */ 262 bool ConnectFailSafe (std::string name, const CallbackBase &cb); 263 /** 264 * \param [in] name The name of the trace source to connect to 265 * \param [in] cb The sink to connect to the trace source 266 * 267 * Connect the specified sink to all the objects stored in this 268 * container. This method will raise a fatal error if no objects could 269 * be connected; use ConnectWithoutContextFailSafe if no connections is 270 * a valid possible outcome. 271 * \sa ns3::Config::ConnectWithoutContext 272 */ 273 void ConnectWithoutContext (std::string name, const CallbackBase &cb); 274 /** 275 * Connect the specified sink to all the objects stored in this 276 * container. This method will return true if any trace sources could be 277 * connected, and false otherwise. 278 * \returns \c true if any trace sources could be connected. 279 */ 280 bool ConnectWithoutContextFailSafe (std::string name, const CallbackBase &cb); 281 /** 282 * \param [in] name The name of the trace source to disconnect from 283 * \param [in] cb The sink to disconnect from the trace source 284 * 285 * Disconnect the specified sink from all the objects stored in this 286 * container. 287 * \sa ns3::Config::Disconnect 288 */ 289 void Disconnect (std::string name, const CallbackBase &cb); 290 /** 291 * \param [in] name The name of the trace source to disconnect from 292 * \param [in] cb The sink to disconnect from the trace source 293 * 294 * Disconnect the specified sink from all the objects stored in this 295 * container. 296 * \sa ns3::Config::DisconnectWithoutContext 297 */ 298 void DisconnectWithoutContext (std::string name, const CallbackBase &cb); 299 300 private: 301 /** The list of objects in this container. */ 302 std::vector<Ptr<Object> > m_objects; 303 /** The context for each object. */ 304 std::vector<std::string> m_contexts; 305 /** The path used to perform the object matching. */ 306 std::string m_path; 307 }; 308 309 /** 310 * \ingroup config 311 * \param [in] path The path to perform a match against 312 * \returns A container which contains all the objects which match the input 313 * path. 314 */ 315 MatchContainer LookupMatches (std::string path); 316 317 /** 318 * \ingroup config 319 * \param [in] obj A new root object 320 * 321 * Each root object is used during path matching as 322 * the root of the path by Config::Connect, and Config::Set. 323 */ 324 void RegisterRootNamespaceObject (Ptr<Object> obj); 325 /** 326 * \ingroup config 327 * \param [in] obj A new root object 328 * 329 * This function undoes the work of Config::RegisterRootNamespaceObject. 330 */ 331 void UnregisterRootNamespaceObject (Ptr<Object> obj); 332 333 /** 334 * \ingroup config 335 * \returns The number of registered root namespace objects. 336 */ 337 std::size_t GetRootNamespaceObjectN (void); 338 339 /** 340 * \ingroup config 341 * \param [in] i The index of the requested object. 342 * \returns The requested root namespace object 343 */ 344 Ptr<Object> GetRootNamespaceObject (uint32_t i); 345 346 } // namespace Config 347 348 } // namespace ns3 349 350 #endif /* CONFIG_H */ 351