A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
attribute.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef ATTRIBUTE_H
9#define ATTRIBUTE_H
10
11#include "ptr.h"
12#include "simple-ref-count.h"
13
14#include <stdint.h>
15#include <string>
16
17/**
18 * \file
19 * \ingroup attributes
20 * ns3::AttributeValue, ns3::AttributeAccessor and
21 * ns3::AttributeChecker declarations.
22 */
23
24namespace ns3
25{
26
27class AttributeAccessor;
28class AttributeChecker;
29class Attribute;
30class ObjectBase;
31
32/**
33 *
34 * \ingroup core
35 * \defgroup attributes Attributes
36 *
37 * The \c ns-3 attribute system is the mechanism used in \c ns-3 to
38 * organize, document, and modify the *values* used by the various
39 * component models.
40 *
41 * Attributes also enable the tracing and statistics gathering
42 * in the simulator.
43 *
44 * See \ref attributehelper for macros to ease the declaration
45 * and definition of Attributes.
46 */
47
48/**
49 *
50 * \ingroup attributes
51 *
52 * \brief Hold a value for an Attribute.
53 *
54 * Instances of this class should always be wrapped into an Attribute object.
55 * Most subclasses of this base class are implemented by the
56 * ATTRIBUTE_HELPER_* macros.
57 */
58class AttributeValue : public SimpleRefCount<AttributeValue>
59{
60 public:
62 virtual ~AttributeValue();
63
64 /**
65 * \returns a deep copy of this class, wrapped into an Attribute object.
66 */
67 virtual Ptr<AttributeValue> Copy() const = 0;
68 /**
69 * \param [in] checker The checker associated to the attribute
70 * \returns A string representation of this value.
71 *
72 * In most cases, this method will not make any use of the checker argument.
73 * However, in a very limited set of cases, the checker argument is needed to
74 * perform proper serialization. A nice example of code which needs it is
75 * the EnumValue::SerializeToString code.
76 */
77 virtual std::string SerializeToString(Ptr<const AttributeChecker> checker) const = 0;
78 /**
79 * \param [in] value A string representation of the value
80 * \param [in] checker A pointer to the checker associated to the attribute.
81 * \returns true if the input string was correctly-formatted and could be
82 * successfully deserialized, false otherwise.
83 *
84 * Upon return of this function, this AttributeValue instance contains
85 * the deserialized value.
86 * In most cases, this method will not make any use of the checker argument.
87 * However, in a very limited set of cases, the checker argument is needed to
88 * perform proper serialization. A nice example of code which needs it is
89 * the EnumValue::SerializeToString code.
90 */
91 virtual bool DeserializeFromString(std::string value, Ptr<const AttributeChecker> checker) = 0;
92};
93
94/**
95 * \brief allow setting and getting the value of an attribute.
96 *
97 * \ingroup attributes
98 *
99 * The goal of this class is to hide from the user how an attribute
100 * is actually set or get to or from a class instance. Implementations
101 * of this base class are usually provided through the MakeAccessorHelper
102 * template functions, hidden behind an ATTRIBUTE_HELPER_* macro.
103 */
104class AttributeAccessor : public SimpleRefCount<AttributeAccessor>
105{
106 public:
108 virtual ~AttributeAccessor();
109
110 /**
111 * \param [in,out] object The object instance to set the value in
112 * \param [in] value The value to set
113 * \returns true if the value could be set successfully, false otherwise.
114 *
115 * This method expects that the caller has checked that the input value is
116 * valid with AttributeChecker::Check.
117 */
118 virtual bool Set(ObjectBase* object, const AttributeValue& value) const = 0;
119 /**
120 * \param [in,out] object The object instance to get the value from
121 * \param [out] attribute A pointer to where the value should be set.
122 * \returns true if the value could be read successfully, and
123 * stored in the input value, false otherwise.
124 *
125 * This method expects that the caller has checked that the input value is
126 * valid with AttributeChecker::Check.
127 */
128 virtual bool Get(const ObjectBase* object, AttributeValue& attribute) const = 0;
129
130 /**
131 * \return true if this accessor supports the Get operation, false
132 * otherwise.
133 */
134 virtual bool HasGetter() const = 0;
135 /**
136 * \return true if this accessor supports the Set operation, false
137 * otherwise.
138 */
139 virtual bool HasSetter() const = 0;
140};
141
142/**
143 * \brief Represent the type of an attribute
144 *
145 * \ingroup attributes
146 *
147 * Each type of attribute has an associated unique AttributeChecker
148 * subclass. The type of the subclass can be safely used by users
149 * to infer the type of the associated attribute. i.e., we expect
150 * binding authors to use the checker associated to an attribute
151 * to detect the type of the associated attribute.
152 *
153 * Most subclasses of this base class are implemented by the
154 * ATTRIBUTE_HELPER_HEADER and ATTRIBUTE_HELPER_CPP macros.
155 */
156class AttributeChecker : public SimpleRefCount<AttributeChecker>
157{
158 public:
160 virtual ~AttributeChecker();
161
162 /**
163 * Create a valid value from the argument value,
164 * or reinterpret the argument as a string.
165 *
166 * \param [in] value The AttributeValue to check
167 * \return Ptr to a valid value
168 */
170 /**
171 * \param [in] value A pointer to the value to check
172 * \returns true if the input value is both of the right type
173 * and if its value is within the requested range. Returns
174 * false otherwise.
175 */
176 virtual bool Check(const AttributeValue& value) const = 0;
177 /**
178 * \returns the c++ fully-qualified typename of the subclass
179 * of the ns3::AttributeValue base class which is associated
180 * to this checker.
181 *
182 * A typical return value here is FooValue where Foo is the name of the
183 * type being wrapped.
184 */
185 virtual std::string GetValueTypeName() const = 0;
186 /**
187 * \returns true if this checker has information about the underlying
188 * C++ type, false otherwise.
189 *
190 * If this method returns false, the return value of the GetUnderlyingTypeInformation
191 * method cannot be relied upon.
192 */
193 virtual bool HasUnderlyingTypeInformation() const = 0;
194 /**
195 * \returns a human-readable representation of information about
196 * the underlying C++ type.
197 */
198 virtual std::string GetUnderlyingTypeInformation() const = 0;
199 /**
200 * \returns a new instance of an AttributeValue (wrapper in an Attribute
201 * instance) which matches the type of the underlying attribute.
202 *
203 * This method is typically used to create a temporary variable prior
204 * to calling Attribute::DeserializeFromString.
205 */
206 virtual Ptr<AttributeValue> Create() const = 0;
207 /**
208 * Copy the source to the destination
209
210 * \param [in] source Source AttributeValue
211 * \param [out] destination Destination AttributeValue
212 * \return true if copy was successful
213 */
214 virtual bool Copy(const AttributeValue& source, AttributeValue& destination) const = 0;
215};
216
217/**
218 * \ingroup attributes
219 * \defgroup attribute_EmptyAttribute EmptyAttribute Attribute
220 * AttributeValue implementation for EmptyAttribute
221 */
222
223/**
224 * \brief A class for an empty attribute value.
225 *
226 * \ingroup attribute_EmptyAttribute
227 *
228 * \see AttributeValue
229 */
231{
232 public:
233 /** Default constructor. */
235
236 private:
237 /**
238 * \returns a deep copy of this class, wrapped into an Attribute object.
239 */
240 Ptr<AttributeValue> Copy() const override;
241 /**
242 * \param [in] checker The checker associated to the attribute
243 * \returns a string representation of this value.
244 *
245 * In the EmptyAttributeValue case, the string returned will be simply ""
246 */
247 std::string SerializeToString(Ptr<const AttributeChecker> checker) const override;
248 /**
249 * \param [in] value A string representation of the value
250 * \param [in] checker A pointer to the checker associated to the attribute.
251 * \returns true if the input string was correctly-formatted and could be
252 * successfully deserialized, false otherwise.
253 *
254 * In the trivial case of EmptyAttributeValue, this should always return true
255 */
256 bool DeserializeFromString(std::string value, Ptr<const AttributeChecker> checker) override;
257};
258
259/**
260 * \brief An accessor for EmptyAttributeValue
261 *
262 * \ingroup attribute_EmptyAttribute
263 *
264 * Does nothing, since every EmptyAttributeValue is the same.
265 */
267{
268 public:
270 ~EmptyAttributeAccessor() override;
271 bool Set(ObjectBase* object, const AttributeValue& value) const override;
272 bool Get(const ObjectBase* object, AttributeValue& attribute) const override;
273 bool HasGetter() const override;
274 bool HasSetter() const override;
275};
276
277/**
278 * \ingroup attribute_EmptyAttribute
279 *
280 * \brief Create an empty AttributeAccessor.
281 *
282 * \returns The empty AttributeAccessor (runtime exception if used)
283 */
289
290/**
291 * \brief A checker for EmptyAttributeValue
292 *
293 * \ingroup attribute_EmptyAttribute
294 *
295 * Does nothing, since every EmptyAttributeValue does not contain anything and
296 * is, of course, valid.
297 */
299{
300 public:
302 ~EmptyAttributeChecker() override;
303 bool Check(const AttributeValue& value) const override;
304 std::string GetValueTypeName() const override;
305 bool HasUnderlyingTypeInformation() const override;
306 std::string GetUnderlyingTypeInformation() const override;
307 Ptr<AttributeValue> Create() const override;
308 bool Copy(const AttributeValue& source, AttributeValue& destination) const override;
309};
310
311/**
312 * \ingroup attribute_EmptyAttribute
313 *
314 * \brief Create an empty AttributeChecker.
315 *
316 * \returns The empty AttributeChecker (runtime exception if used)
317 */
318static inline Ptr<AttributeChecker>
323
324} // namespace ns3
325
326#endif /* ATTRIBUTE_H */
allow setting and getting the value of an attribute.
Definition attribute.h:105
virtual bool Get(const ObjectBase *object, AttributeValue &attribute) const =0
virtual bool Set(ObjectBase *object, const AttributeValue &value) const =0
virtual bool HasSetter() const =0
virtual bool HasGetter() const =0
virtual ~AttributeAccessor()
Definition attribute.cc:40
Represent the type of an attribute.
Definition attribute.h:157
virtual bool HasUnderlyingTypeInformation() const =0
virtual ~AttributeChecker()
Definition attribute.cc:48
virtual std::string GetValueTypeName() const =0
virtual bool Check(const AttributeValue &value) const =0
virtual bool Copy(const AttributeValue &source, AttributeValue &destination) const =0
Copy the source to the destination.
Ptr< AttributeValue > CreateValidValue(const AttributeValue &value) const
Create a valid value from the argument value, or reinterpret the argument as a string.
Definition attribute.cc:53
virtual std::string GetUnderlyingTypeInformation() const =0
virtual Ptr< AttributeValue > Create() const =0
Hold a value for an Attribute.
Definition attribute.h:59
virtual bool DeserializeFromString(std::string value, Ptr< const AttributeChecker > checker)=0
virtual Ptr< AttributeValue > Copy() const =0
virtual ~AttributeValue()
Definition attribute.cc:32
virtual std::string SerializeToString(Ptr< const AttributeChecker > checker) const =0
An accessor for EmptyAttributeValue.
Definition attribute.h:267
bool Get(const ObjectBase *object, AttributeValue &attribute) const override
Definition attribute.cc:124
bool Set(ObjectBase *object, const AttributeValue &value) const override
Definition attribute.cc:117
bool HasSetter() const override
Definition attribute.cc:137
bool HasGetter() const override
Definition attribute.cc:131
A checker for EmptyAttributeValue.
Definition attribute.h:299
std::string GetValueTypeName() const override
Definition attribute.cc:158
bool Check(const AttributeValue &value) const override
Definition attribute.cc:152
Ptr< AttributeValue > Create() const override
Definition attribute.cc:176
bool Copy(const AttributeValue &source, AttributeValue &destination) const override
Copy the source to the destination.
Definition attribute.cc:183
bool HasUnderlyingTypeInformation() const override
Definition attribute.cc:164
~EmptyAttributeChecker() override
Definition attribute.cc:147
std::string GetUnderlyingTypeInformation() const override
Definition attribute.cc:170
A class for an empty attribute value.
Definition attribute.h:231
std::string SerializeToString(Ptr< const AttributeChecker > checker) const override
Definition attribute.cc:94
EmptyAttributeValue()
Default constructor.
Definition attribute.cc:81
Ptr< AttributeValue > Copy() const override
Definition attribute.cc:87
bool DeserializeFromString(std::string value, Ptr< const AttributeChecker > checker) override
Definition attribute.cc:101
Anchor the ns-3 type and attribute system.
Smart pointer class similar to boost::intrusive_ptr.
A template-based reference counting class.
static Ptr< AttributeChecker > MakeEmptyAttributeChecker()
Create an empty AttributeChecker.
Definition attribute.h:319
static Ptr< const AttributeAccessor > MakeEmptyAttributeAccessor()
Create an empty AttributeAccessor.
Definition attribute.h:285
Every class exported by the ns3 library is enclosed in the ns3 namespace.
ns3::Ptr smart pointer declaration and implementation.
ns3::SimpleRefCount declaration and template implementation.