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 OBJECT_BASE_H
21 #define OBJECT_BASE_H
22
23 #include "type-id.h"
24 #include "callback.h"
25 #include <string>
26 #include <list>
27
28 /**
29 * \file
30 * \ingroup object
31 * ns3::ObjectBase declaration and
32 * NS_OBJECT_ENSURE_REGISTERED() madro definition.
33 */
34
35 /**
36 * \ingroup object
37 * \brief Register an Object subclass with the TypeId system.
38 *
39 * This macro should be invoked once for every class which
40 * defines a new GetTypeId method.
41 *
42 * If the class is in a namespace, then the macro call should also be
43 * in the namespace.
44 */
45 #define NS_OBJECT_ENSURE_REGISTERED(type) \
46 static struct Object ## type ## RegistrationClass \
47 { \
48 Object ## type ## RegistrationClass () { \
49 ns3::TypeId tid = type::GetTypeId (); \
50 tid.SetSize (sizeof (type)); \
51 tid.GetParent (); \
52 } \
53 } Object ## type ## RegistrationVariable
54
55
56 /**
57 * \ingroup object
58 * \brief Explicitly instantiate a template class and register the resulting
59 * instance with the TypeId system.
60 *
61 * This macro should be invoked once for every required instance of a template
62 * class which derives from the Object class and defines a new GetTypeId method.
63 *
64 * If the template class is in a namespace, then the macro call should also be
65 * in the namespace.
66 */
67 #define NS_OBJECT_TEMPLATE_CLASS_DEFINE(type,param) \
68 template class type<param>; \
69 template <> std::string DoGetTypeParamName<type<param> > () \
70 { \
71 return #param; \
72 } \
73 static struct Object ## type ## param ## RegistrationClass \
74 { \
75 Object ## type ## param ## RegistrationClass () { \
76 ns3::TypeId tid = type<param>::GetTypeId (); \
77 tid.SetSize (sizeof (type<param>)); \
78 tid.GetParent (); \
79 } \
80 } Object ## type ## param ## RegistrationVariable
81
82
83 namespace ns3 {
84
85 /**
86 * \brief Helper function to get the name (as a string) of the type parameter
87 * of a template class
88 * \return the name of the type parameter as a string
89 *
90 * A specialization of this function is defined by the
91 * NS_OBJECT_TEMPLATE_CLASS_DEFINE macro.
92 */
93 template <typename T>
94 std::string DoGetTypeParamName (void);
95
96 /**
97 * \brief Helper function to get the name (as a string) of the type parameter
98 * of a template class
99 * \return the name of the type parameter as a string
100 */
101 template <typename T>
GetTypeParamName(void)102 std::string GetTypeParamName (void)
103 {
104 return DoGetTypeParamName<T> ();
105 }
106
107 class AttributeConstructionList;
108
109 /**
110 * \ingroup object
111 *
112 * \brief Anchor the ns-3 type and attribute system.
113 *
114 * Every class which wants to integrate in the ns-3 type and attribute
115 * system should derive from this base class. This base class provides:
116 * - A way to associate an ns3::TypeId to each object instance.
117 * - A way to set and get the attributes registered in the ns3::TypeId.
118 */
119 class ObjectBase
120 {
121 public:
122 /**
123 * Get the type ID.
124 * \return The object TypeId.
125 */
126 static TypeId GetTypeId (void);
127
128 /**
129 * Virtual destructor.
130 */
131 virtual ~ObjectBase ();
132
133 /**
134 * Get the most derived TypeId for this Object.
135 *
136 * This method is typically implemented by ns3::Object::GetInstanceTypeId
137 * but some classes which derive from ns3::ObjectBase directly
138 * have to implement it themselves.
139 *
140 * \return The TypeId associated to the most-derived type
141 * of this instance.
142 */
143 virtual TypeId GetInstanceTypeId (void) const = 0;
144
145 /**
146 *
147 * Set a single attribute, raising fatal errors if unsuccessful.
148 *
149 * This will either succeed at setting the attribute
150 * or it will raise NS_FATAL_ERROR() on these conditions:
151 *
152 * - The attribute doesn't exist in this Object.
153 * - The attribute can't be set (no Setter).
154 * - The attribute couldn't be deserialized from the AttributeValue.
155 *
156 * \param [in] name The name of the attribute to set.
157 * \param [in] value The name of the attribute to set.
158 */
159 void SetAttribute (std::string name, const AttributeValue &value);
160 /**
161 * Set a single attribute without raising errors.
162 *
163 * If the attribute could not be set this will return \c false,
164 * but not raise any errors.
165 *
166 * \param [in] name The name of the attribute to set.
167 * \param [in] value The value to set it to.
168 * \return \c true if the requested attribute exists and could be set,
169 * \c false otherwise.
170 */
171 bool SetAttributeFailSafe (std::string name, const AttributeValue &value);
172 /**
173 * Get the value of an attribute, raising fatal errors if unsuccessful.
174 *
175 * This will either succeed at setting the attribute
176 * or it will raise NS_FATAL_ERROR() on these conditions:
177 *
178 * - The attribute doesn't exist in this Object.
179 * - The attribute can't be read (no Getter).
180 * - The attribute doesn't support string formatting.
181 * - The attribute couldn't be serialized into the AttributeValue.
182 *
183 * \param [in] name The name of the attribute to read.
184 * \param [out] value Where the result should be stored.
185 */
186 void GetAttribute (std::string name, AttributeValue &value) const;
187 /**
188 * Get the value of an attribute without raising erros.
189 *
190 * If the attribute could not be read this will return \c false,
191 * but not raise any errors.
192 *
193 * \param [in] name The name of the attribute to read.
194 * \param [out] value Where the result value should be stored.
195 * \return \c true if the requested attribute was found, \c false otherwise.
196 */
197 bool GetAttributeFailSafe (std::string name, AttributeValue &value) const;
198
199 /**
200 * Connect a TraceSource to a Callback with a context.
201 *
202 * The target trace source should be registered with TypeId::AddTraceSource.
203 *
204 * \param [in] name The name of the target trace source.
205 * \param [in] context The trace context associated to the callback.
206 * \param [in] cb The callback to connect to the trace source.
207 * \returns \c true on success, \c false if TraceSource was not found.
208 */
209 bool TraceConnect (std::string name, std::string context, const CallbackBase &cb);
210 /**
211 * Connect a TraceSource to a Callback without a context.
212 *
213 * The target trace source should be registered with TypeId::AddTraceSource.
214 *
215 * \param [in] name The name of the target trace source.
216 * \param [in] cb The callback to connect to the trace source.
217 * \returns \c true on success, \c false if TraceSource was not found.
218 */
219 bool TraceConnectWithoutContext (std::string name, const CallbackBase &cb);
220 /**
221 * Disconnect from a TraceSource a Callback previously connected
222 * with a context.
223 *
224 * The target trace source should be registered with TypeId::AddTraceSource.
225 *
226 * \param [in] name The name of the target trace source.
227 * \param [in] context The trace context associated to the callback.
228 * \param [in] cb The callback to disconnect from the trace source.
229 * \returns \c true on success, \c false if TraceSource was not found.
230 */
231 bool TraceDisconnect (std::string name, std::string context, const CallbackBase &cb);
232 /**
233 * Disconnect from a TraceSource a Callback previously connected
234 * without a context.
235 *
236 * The target trace source should be registered with TypeId::AddTraceSource.
237 *
238 * \param [in] name The name of the target trace source.
239 * \param [in] cb The callback to disconnect from the trace source.
240 * \returns \c true on success, \c false if TraceSource was not found.
241 */
242 bool TraceDisconnectWithoutContext (std::string name, const CallbackBase &cb);
243
244 protected:
245 /**
246 * Notifier called once the ObjectBase is fully constructed.
247 *
248 * This method is invoked once all member attributes have been
249 * initialized. Subclasses can override this method to be notified
250 * of this event but if they do this, they must chain up to their
251 * parent's NotifyConstructionCompleted method.
252 */
253 virtual void NotifyConstructionCompleted (void);
254 /**
255 * Complete construction of ObjectBase; invoked by derived classes.
256 *
257 * Invoked from subclasses to initialize all of their
258 * attribute members. This method will typically be invoked
259 * automatically from ns3::CreateObject if your class derives
260 * from ns3::Object. If you derive from ns3::ObjectBase directly,
261 * you should make sure that you invoke this method from
262 * your most-derived constructor.
263 *
264 * \param [in] attributes The attribute values used to initialize
265 * the member variables of this object's instance.
266 */
267 void ConstructSelf (const AttributeConstructionList &attributes);
268
269 private:
270 /**
271 * Attempt to set the value referenced by the accessor \pname{spec}
272 * to a valid value according to the \c checker, based on \pname{value}.
273 *
274 * \param [in] spec The accessor for the storage location.
275 * \param [in] checker The checker to use in validating the value.
276 * \param [in] value The value to attempt to store.
277 * \returns \c true if the \c value could be validated by the \pname{checker}
278 * and written to the storage location.
279 */
280 bool DoSet (Ptr<const AttributeAccessor> spec,
281 Ptr<const AttributeChecker> checker,
282 const AttributeValue &value);
283
284 };
285
286 } // namespace ns3
287
288 #endif /* OBJECT_BASE_H */
289