# class Message

A message container class. More...

Full name | `TelEngine::Message`
Definition | `#include <yatengine.h>`
Inherits | TelEngine::NamedList [public ]
List of all Methods

Annotated List
Files
Globals
Hierarchy
Index

#### Public Methods

- explicit Message (const char* name, const char* retval = 0, bool broadcast = false)
- Message (const Message& original)
- Message (const Message& original, bool broadcast)
- ~Message ()
- virtual void* getObject (const String& name) const
- inline String& retValue ()
- inline const String& retValue () const
- inline RefObject* userData () const
- void userData (RefObject* data)
- inline void* userObject (const String& name) const
- inline void setNotify (bool notify = true)
- inline bool broadcast () const
- inline Time& msgTime ()
- inline const Time& msgTime () const
- inline Message& operator= (const char* value)
- String encode (const char* id) const
- String encode (bool received, const char* id) const
- int decode (const char* str, String& id)
- int decode (const char* str, bool& received, const char* id)

#### Protected Methods

- virtual void dispatched (bool accepted)

## Detailed Description

This class holds the messages that are moved around in the engine.

explicit Message (const char* name, const char* retval = 0, bool broadcast = false)

### Message

Creates a new message.

Parameters:

name | Name of the message - must not be NULL or empty
retval | Default return value
broadcast | Broadcast flag, true if handling the mesage must not stop it

Message (const Message& original)

### Message

Copy constructor. Note that user data and notification are not copied

Parameters:

original | Message we are copying from

Message (const Message& original, bool broadcast)

### Message

Copy constructor that can alter the broadcast flag. Note that user data and notification are not copied

Parameters:

original | Message we are copying from
broadcast | Broadcast flag, true if handling the mesage must not stop it

~Message ()

### ~Message

Destruct the message and dereferences any user data

void* getObject (const String& name)

### getObject

[const virtual]

Get a pointer to a derived class given that class name

Parameters:

name | Name of the class we are asking for

Returns: Pointer to the requested class or NULL if this object doesn't implement it

Reimplemented from NamedList.

inline String& retValue ()

### retValue

Retrieve a reference to the value returned by the message.

Returns: A reference to the value the message will return

inline const String& retValue ()

### retValue

[const]

Retrieve a const reference to the value returned by the message.

Returns: A reference to the value the message will return

inline RefObject* userData ()

### userData

[const]

Retrieve the object associated with the message

Returns: Pointer to arbitrary user RefObject

void userData (RefObject* data)

### userData

Set obscure data associated with the message. The user data is reference counted to avoid stray pointers. Note that setting new user data will disable any notification.

Parameters:

data | Pointer to arbitrary user data

inline void* userObject (const String& name)

### userObject

[const]

Get a pointer to a derived class of user data given that class name

Parameters:

name | Name of the class we are asking for

Returns: Pointer to the requested class or NULL if user object id NULL or doesn't implement it

inline void setNotify (bool notify = true)

### setNotify

Enable or disable notification of any MessageNotifier that was set as user data. This method must be called after userData()

Parameters:

notify | True to have the message call the notifier

inline bool broadcast ()

### broadcast

[const]

Retrieve the broadcast flag

Returns: True if the message is a broadcast (handling does not stop it)

inline Time& msgTime ()

### msgTime

Retrieve a reference to the creation time of the message.

Returns: A reference to the Time when the message was created

inline const Time& msgTime ()

### msgTime

[const]

Retrieve a const reference to the creation time of the message.

Returns: A reference to the Time when the message was created

inline Message& operator= (const char* value)

### operator=

Name assignment operator

Reimplemented from NamedList.

String encode (const char* id)

### encode

[const]

Encode the message into a string adequate for sending for processing to an external communication interface

Parameters:

id | Unique identifier to add to the string

String encode (bool received, const char* id)

### encode

[const]

Encode the message into a string adequate for sending as answer to an external communication interface

Parameters:

received | True if message was processed locally
id | Unique identifier to add to the string

int decode (const char* str, String& id)

### decode

Decode a string from an external communication interface for processing in the engine. The message is modified accordingly.

Parameters:

str | String to decode
id | A String object in which the identifier is stored

Returns: -2 for success, -1 if the string was not a text form of a message, index of first erroneous character if failed

int decode (const char* str, bool& received, const char* id)

### decode

Decode a string from an external communication interface that is an answer to a specific external processing request.

Parameters:

str | String to decode
received | Pointer to variable to store the dispatch return value
id | The identifier expected

Returns: -2 for success, -1 if the string was not the expected answer, index of first erroneous character if failed

void dispatched (bool accepted)

### dispatched

[protected virtual]

Notify the message it has been dispatched. The default behaviour is to call the dispatched() method of the user data if it implements MessageNotifier

Parameters:

accepted | True if one handler accepted the message

Generated by: paulc on bussard on Fri Dec 21 16:28:34 2012, using kdoc 2.0a54.