Statistics
| Branch: | Revision:

root / include / cmsgpar.h @ fbe00e73

History | View | Annotate | Download (16.8 KB)

1
//==========================================================================
2
//   CMSGPAR.H  - part of
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//==========================================================================
7

    
8
/*--------------------------------------------------------------*
9
  Copyright (C) 1992-2008 Andras Varga
10
  Copyright (C) 2006-2008 OpenSim Ltd.
11

12
  This file is distributed WITHOUT ANY WARRANTY. See the file
13
  `license' for details on this and other legal matters.
14
*--------------------------------------------------------------*/
15

    
16
#ifndef __CMSGPAR_H
17
#define __CMSGPAR_H
18

    
19
#include "cownedobject.h"
20
#include "cmathfunction.h"
21

    
22
NAMESPACE_BEGIN
23

    
24
class  cStatistic;
25
class  cXMLElement;
26

    
27

    
28
/**
29
 * cMsgPar objects store a (string, bool, double, etc) value, and
30
 * can be attached to cMessage objects.
31
 *
32
 * <b>Note:</b> Before version 3.0, the cPar class was used for both
33
 * message parameters and module parameters. As of 4.0, cPar only
34
 * serves as module/channel parameter, and other uses of cPar in
35
 * existing 3.x code should be either eliminated (see next note),
36
 * or changed to cMsgPar.
37
 *
38
 * <b>Note2:</b> This is an obsolete class, retained to support legacy code.
39
 * The preferred way of adding data to cMessages since the 2.3 version is
40
 * via subclassing, using <tt>.msg</tt> files and the <i>opp_msgc</i> tool.
41
 *
42
 * cMsgPar supports several data types. Data types are identified by type
43
 * characters. The current data type is returned by getType().
44
 *     - basic types: <b>S</b> string, <b>B</b> bool, <b>L</b> long, <b>D</b> double
45
 *     - <b>F</b> math function (MathFuncNoArgs,MathFunc1Args,etc),
46
 *     - <b>T</b> a statistic object (subclassed from cStatistic)
47
 *     - <b>P</b> pointer to cOwnedObject,
48
 *     - <b>M</b> XML element (pointer to a cXMLElement)
49
 *
50
 * @ingroup SimCore
51
 */
52
class SIM_API cMsgPar : public cOwnedObject
53
{
54
  protected:
55
    static const char *possibletypes;
56

    
57
  private:
58
    enum { SHORTSTR_MAXLEN = 27 };
59

    
60
    char typechar;     // S/B/L/D/F/T/P/O
61
    bool changedflag;
62
    bool tkownership;
63

    
64
    union {
65
       struct { bool sht; char *str;  } ls;   // S:long string
66
       struct { bool sht; char str[SHORTSTR_MAXLEN+1]; } ss;  // S:short str
67
       struct { long val;             } lng;  // L:long,B:bool
68
       struct { double val;           } dbl;  // D:double
69
       struct { MathFunc f; int argc;
70
                double p1,p2,p3,p4;   } func; // F:math function
71
       struct { cStatistic *res;      } dtr;  // T:distribution
72
       struct { void *ptr;
73
                VoidDelFunc delfunc;
74
                VoidDupFunc dupfunc;
75
                size_t itemsize;      } ptr;  // P:void* pointer
76
       struct { cOwnedObject *obj;    } obj;  // O:object pointer
77
       struct { cXMLElement *node;    } xmlp; // M:XML element pointer
78
    };
79

    
80
  private:
81
    // helper func: destruct old value
82
    void deleteOld();
83

    
84
    // helper func: rand.num with given distr.(T)
85
    double getFromstat();
86

    
87
    // setFromText() helper func.
88
    bool setfunction(char *w);
89

    
90
  protected:
91
    /** @name Event hooks */
92
    //@{
93

    
94
    /**
95
     * Called each time before the value of this object changes.
96
     * It can be used for tracking parameter changes.
97
     * This default implementation does nothing.
98
     */
99
    virtual void beforeChange();
100

    
101
    /**
102
     * Called each time after the value of this object changed.
103
     * It can be used for tracking parameter changes.
104
     * This default implementation does nothing.
105
     */
106
    virtual void afterChange();
107
    //@}
108

    
109
  public:
110
    /** @name Constructors, destructor, assignment. */
111
    //@{
112

    
113
    /**
114
     * Copy constructor, creates an exact copy of the argument.
115
     */
116
    cMsgPar(const cMsgPar& other);
117

    
118
    /**
119
     * Constructor, creates a cMsgPar with the given name and long
120
     * ('L') as default type.
121
     */
122
    explicit cMsgPar(const char *name=NULL);
123

    
124
    /**
125
     * Constructor, creates a copy of the second argument with another
126
     * name.
127
     */
128
    explicit cMsgPar(const char *name, cMsgPar& other);
129

    
130
    /**
131
     * Destructor.
132
     */
133
    virtual ~cMsgPar();
134

    
135
    /**
136
     * Assignment operator. The name member is not copied; see cOwnedObject's
137
     * operator=() for more details.
138
     *
139
     * The behavior with redirected cMsgPar objects is the following. This function
140
     * copies the contents of the other object (whether it is redirected or not)
141
     * into this object, <b>or,</b> if this object is redirected, into the object
142
     * this object refers to. This means that if you want to overwrite this
143
     * very object (and not the one it points to), you have to use
144
     * cancelRedirection() first.
145
     */
146
    cMsgPar& operator=(const cMsgPar& otherpar);
147
    //@}
148

    
149
    /** @name Redefined cObject member functions */
150
    //@{
151

    
152
    /**
153
     * Creates and returns an exact copy of this object.
154
     * See cObject for more details.
155
     */
156
    virtual cMsgPar *dup() const  {return new cMsgPar(*this);}
157

    
158
    /**
159
     * Produces a one-line description of the object's contents.
160
     * See cObject for more details.
161
     */
162
    virtual std::string info() const;
163

    
164
    /**
165
     * Produces a multi-line description of the object's contents.
166
     * See cObject for more details.
167
     */
168
    virtual std::string detailedInfo() const;
169

    
170
    /**
171
     * Calls v->visit(this) for the contained object, if there is any.
172
     * See cObject for more details.
173
     */
174
    virtual void forEachChild(cVisitor *v);
175

    
176
    /**
177
     * Serializes the object into an MPI send buffer.
178
     * Used by the simulation kernel for parallel execution.
179
     * See cObject for more details.
180
     */
181
    virtual void parsimPack(cCommBuffer *buffer);
182

    
183
    /**
184
     * Deserializes the object from an MPI receive buffer
185
     * Used by the simulation kernel for parallel execution.
186
     * See cObject for more details.
187
     */
188
    virtual void parsimUnpack(cCommBuffer *buffer);
189
    //@}
190

    
191
    /** @name Setter functions. Note that overloaded assignment operators also exist. */
192
    //@{
193

    
194
    /**
195
     * Sets the value to the given bool value.
196
     */
197
    cMsgPar& setBoolValue(bool b);
198

    
199
    /**
200
     * Sets the value to the given long value.
201
     */
202
    cMsgPar& setLongValue(long l);
203

    
204
    /**
205
     * Sets the value to the given string value.
206
     * The cMsgPar will make its own copy of the string. NULL is also accepted
207
     * and treated as an empty string.
208
     */
209
    cMsgPar& setStringValue(const char *s);
210

    
211
    /**
212
     * Sets the value to the given double value.
213
     */
214
    cMsgPar& setDoubleValue(double d);
215

    
216
    /**
217
     * Sets the value to the given distribution.
218
     * Every time the cMsgPar's value is asked a random number produced
219
     * by res.random() will be returned.
220
     */
221
    cMsgPar& setDoubleValue(cStatistic *res);
222

    
223
    /**
224
     * Sets the value to the given math function with no arguments.
225
     * Every time the cMsgPar's value is asked the function will be called.
226
     */
227
    cMsgPar& setDoubleValue(MathFuncNoArg f);
228

    
229
    /**
230
     * Sets the value to the given math function with one argument.
231
     * Every time the cMsgPar's value is asked the function will be called
232
     * with p1 as an argument.
233
     */
234
    cMsgPar& setDoubleValue(MathFunc1Arg  f, double p1);
235

    
236
    /**
237
     * Sets the value to the given math function with two arguments.
238
     * Every time the cMsgPar's value is asked the function will be called
239
     * with p1 and p2 as an arguments.
240
     */
241
    cMsgPar& setDoubleValue(MathFunc2Args f, double p1, double p2);
242

    
243
    /**
244
     * Sets the value to the given math function with three arguments.
245
     * Every time the cMsgPar's value is asked the function will be called
246
     * with p1, p2 and p3 as an arguments.
247
     */
248
    cMsgPar& setDoubleValue(MathFunc3Args f, double p1, double p2, double p3);
249

    
250
    /**
251
     * Sets the value to the given math function with four arguments.
252
     * Every time the cMsgPar's value is asked the function will be called
253
     * with p1, p2, p3 and p4 as an arguments.
254
     */
255
    cMsgPar& setDoubleValue(MathFunc4Args f, double p1, double p2, double p3, double p4);
256

    
257
    /**
258
     * Sets the value to the given pointer. The ownership of the block
259
     * pointer to can be controlled using configPointer().
260
     *
261
     * @see configPointer
262
     */
263
    cMsgPar& setPointerValue(void *ptr);
264

    
265
    /**
266
     * Sets the value to the given object. Whether cMsgPar will take the
267
     * ownership of the object depends on the getTakeOwnership() flag.
268
     */
269
    cMsgPar& setObjectValue(cOwnedObject *obj);
270

    
271
    /**
272
     * Sets the value to the given cXMLElement.
273
     */
274
    cMsgPar& setXMLValue(cXMLElement *node);
275

    
276
    /**
277
     * Configures memory management for the void* pointer ('P') type.
278
     * Similar to cLinkedList::configPointer().
279
     *
280
     * <TABLE BORDER=1>
281
     *   <TR>
282
     *     <TD><b>delfunc</b></TD><TD><b>dupfunc.</b></TD><TD><b>itemsize</b></TD><TD><b>behavior</b></TD>
283
     *   </TR>
284
     *   <TR>
285
     *     <TD>NULL</TD><TD>NULL</TD><TD>0</TD><TD>Pointer is treated as mere pointer - no memory management. Duplication copies the pointer, and deletion does nothing.</TD>
286
     *   </TR>
287
     *   <TR>
288
     *     <TD>NULL</TD><TD>NULL</TD><TD>!=0</TD><TD>Plain memory management. Duplication is done with new char[size]+memcpy(), and deletion is done via delete.</TD>
289
     *   </TR>
290
     *   <TR>
291
     *     <TD>NULL or user's delete func.</TD><TD>user's dupfunc.</TD><TD>indifferent</TD><TD WIDTH=317>Sophisticated memory management. Duplication is done by calling the user-supplied duplication function, which should do the allocation and the appropriate copying. Deletion is done by calling the user-supplied delete function, or the delete operator if it is not supplied.</TD>
292
     *   </TR>
293
     * </TABLE>
294
     */
295
    void configPointer( VoidDelFunc delfunc, VoidDupFunc dupfunc, size_t itemsize=0);
296

    
297
    /**
298
     * Sets the flag that determines whether setObjectValue(cOwnedObject *) and
299
     * setDoubleValue(cStatistic *) should automatically take ownership of
300
     * the objects.
301
     */
302
    void setTakeOwnership(bool tk) {tkownership=tk;}
303

    
304
    /**
305
     * Returns the takeOwnership flag, see getTakeOwnership().
306
     */
307
    bool getTakeOwnership() const   {return tkownership;}
308
    //@}
309

    
310
    /** @name Getter functions. Note that overloaded conversion operators also exist. */
311
    //@{
312

    
313
    /**
314
     * Returns value as a boolean. The cMsgPar type must be bool (B) or a numeric type.
315
     */
316
    bool boolValue();
317

    
318
    /**
319
     * Returns value as long. The cMsgPar type must be types long (L),
320
     * double (D), Boolean (B), function (F), distribution (T).
321
     */
322
    long longValue();
323

    
324
    /**
325
     * Returns value as const char *. Only for string (S) type.
326
     */
327
    const char *stringValue();
328

    
329
    /**
330
     * Returns value as double. The cMsgPar type must be types long (L),
331
     * double (D), function (F), Boolean (B), distribution (T).
332
     */
333
    double doubleValue();
334

    
335
    /**
336
     * Returns value as a void * pointer. The cMsgPar type must be pointer (P).
337
     */
338
    void *pointerValue();
339

    
340
    /**
341
     * Returns value as pointer to cOwnedObject. The cMsgPar type must be pointer (O).
342
     */
343
    cOwnedObject *getObjectValue();
344

    
345
    /**
346
     * Returns value as pointer to cXMLElement. The cMsgPar type must be XML (M).
347
     */
348
    cXMLElement *xmlValue();
349
    //@}
350

    
351
    /** @name Type, change flag. */
352
    //@{
353

    
354
    /**
355
     * Returns type character.
356
     */
357
    char getType() const;
358

    
359
    /**
360
     * Returns true if the stored value is of a numeric type.
361
     */
362
    bool isNumeric() const;
363

    
364
    /**
365
     * Returns true if the value is constant. It returns true if
366
     * the type is 'L', 'D', 'B', or 'S', that is, the object stores
367
     * a long, double, boolean or string constant.
368
     */
369
    bool isConstant() const;
370

    
371
    /**
372
     * Returns true if the value has changed since the last hasChanged() call.
373
     * Side effect: clears the 'changed' flag, so a next call will return
374
     * false.
375
     */
376
    bool hasChanged();
377
    //@}
378

    
379
    /** @name Utility functions. */
380
    //@{
381
    /**
382
     * Replaces the object value with its evaluation (a double).
383
     * Equivalent to <tt>setValue('D', this->doubleValue())</tt>.
384
     */
385
    void convertToConst();
386

    
387
    /**
388
     * Compares the stored values. The two objects must have the same type character
389
     * and the same value to be equal.
390
     */
391
    bool equalsTo(cMsgPar *par);
392
    //@}
393

    
394
    /** @name Convert to/from text representation. */
395
    //@{
396
    /**
397
     * Returns the value in text form.
398
     */
399
    virtual std::string str() const;
400

    
401
    /**
402
     * DEPRECATED. Same as str().
403
     */
404
    _OPPDEPRECATED std::string getAsText() const  {return str();}
405

    
406
    /**
407
     * This function tries to interpret the argument text as a type
408
     * typed value (L=long, S=string, etc). type=='?' (the default)
409
     * means that the type is to be auto-selected. On success,
410
     * cMsgPar is updated with the new value and true is returned,
411
     * otherwise the function returns false. No error message is generated.
412
     */
413
    virtual bool parse(const char *text, char type='?');
414

    
415
    /**
416
     * DEPRECATED. Same as parse().
417
     */
418
    _OPPDEPRECATED bool setFromText(const char *text, char type='?')  {return parse(text, '?');}
419
    //@}
420

    
421
    /** @name Overloaded assignment and conversion operators. */
422
    //@{
423

    
424
    /**
425
     * Equivalent to setBoolValue().
426
     */
427
    cMsgPar& operator=(bool b)  {return setBoolValue(b);}
428

    
429
    /**
430
     * Equivalent to setStringValue().
431
     */
432
    cMsgPar& operator=(const char *s)  {return setStringValue(s);}
433

    
434
    /**
435
     * Converts the argument to long, and calls setLongValue().
436
     */
437
    cMsgPar& operator=(char c)  {return setLongValue((long)c);}
438

    
439
    /**
440
     * Converts the argument to long, and calls setLongValue().
441
     */
442
    cMsgPar& operator=(unsigned char c) {return setLongValue((long)c);}
443

    
444
    /**
445
     * Converts the argument to long, and calls setLongValue().
446
     */
447
    cMsgPar& operator=(int i)  {return setLongValue((long)i);}
448

    
449
    /**
450
     * Converts the argument to long, and calls setLongValue().
451
     */
452
    cMsgPar& operator=(unsigned int i)  {return setLongValue((long)i);}
453

    
454
    /**
455
     * Converts the argument to long, and calls setLongValue().
456
     */
457
    cMsgPar& operator=(short i)  {return setLongValue((long)i);}
458

    
459
    /**
460
     * Converts the argument to long, and calls setLongValue().
461
     */
462
    cMsgPar& operator=(unsigned short i)  {return setLongValue((long)i);}
463

    
464
    /**
465
     * Equivalent to setLongValue().
466
     */
467
    cMsgPar& operator=(long l)  {return setLongValue(l);}
468

    
469
    /**
470
     * Converts the argument to long, and calls setLongValue().
471
     */
472
    cMsgPar& operator=(unsigned long l) {return setLongValue((long)l);}
473

    
474
    /**
475
     * Equivalent to setDoubleValue().
476
     */
477
    cMsgPar& operator=(double d)  {return setDoubleValue(d);}
478

    
479
    /**
480
     * Converts the argument to double, and calls setDoubleValue().
481
     */
482
    cMsgPar& operator=(long double d)  {return setDoubleValue((double)d);}
483

    
484
    /**
485
     * Equivalent to setPointerValue().
486
     */
487
    cMsgPar& operator=(void *ptr)  {return setPointerValue(ptr);}
488

    
489
    /**
490
     * Equivalent to setObjectValue().
491
     */
492
    cMsgPar& operator=(cOwnedObject *obj)  {return setObjectValue(obj);}
493

    
494
    /**
495
     * Equivalent to setXMLValue().
496
     */
497
    cMsgPar& operator=(cXMLElement *node) {return setXMLValue(node);}
498

    
499
    /**
500
     * Equivalent to boolValue().
501
     */
502
    operator bool()  {return boolValue();}
503

    
504
    /**
505
     * Equivalent to stringValue().
506
     */
507
    operator const char *()  {return stringValue();}
508

    
509
    /**
510
     * Calls longValue() and converts the result to char.
511
     */
512
    operator char()  {return (char)longValue();}
513

    
514
    /**
515
     * Calls longValue() and converts the result to unsigned char.
516
     */
517
    operator unsigned char() {return (unsigned char)longValue();}
518

    
519
    /**
520
     * Calls longValue() and converts the result to int.
521
     */
522
    operator int()  {return (int)longValue();}
523

    
524
    /**
525
     * Calls longValue() and converts the result to unsigned int.
526
     */
527
    operator unsigned int()  {return (unsigned int)longValue();}
528

    
529
    /**
530
     * Calls longValue() and converts the result to short.
531
     */
532
    operator short()  {return (short)longValue();}
533

    
534
    /**
535
     * Calls longValue() and converts the result to unsigned short.
536
     */
537
    operator unsigned short()  {return (unsigned short)longValue();}
538

    
539
    /**
540
     * Equivalent to longValue().
541
     */
542
    operator long()  {return longValue();}
543

    
544
    /**
545
     * Calls longValue() and converts the result to unsigned long.
546
     */
547
    operator unsigned long() {return longValue();}
548

    
549
    /**
550
     * Equivalent to doubleValue().
551
     */
552
    operator double()  {return doubleValue();}
553

    
554
    /**
555
     * Calls doubleValue() and converts the result to long double.
556
     */
557
    operator long double()  {return doubleValue();}
558

    
559
    /**
560
     * Equivalent to pointerValue().
561
     */
562
    operator void *()  {return pointerValue();}
563

    
564
    /**
565
     * Equivalent to getObjectValue().
566
     */
567
    operator cOwnedObject *()  {return getObjectValue();}
568

    
569
    /**
570
     * Equivalent to xmlValue().
571
     */
572
    operator cXMLElement *()  {return xmlValue();}
573
    //@}
574
};
575

    
576
NAMESPACE_END
577

    
578

    
579
#endif
580

    
581