Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

os::Message Class Reference

#include <message.h>

List of all members.

Public Methods

 Message (int nCode=0)
 Constructor. More...

 Message (const Message &cMsg)
 Copy constructor. More...

 Message (const void *pFlattenedData)
 Construct a message from a "flattened" buffer. More...

 ~Message ()
 Destructor. More...

int GetCode (void) const
void SetCode (int nCode)
size_t GetFlattenedSize (void) const
 Get the required buffer size needed to "flatten" this message. More...

status_t Flatten (uint8 *pBuffer, size_t nSize) const
 Write the message to a flat data-blob. More...

status_t Unflatten (const uint8 *pBuffer)
 Reconstruct a message from a data-blob created by Flatten(). More...

status_t AddData (const char *pzName, int nType, const void *pData, uint32 nSize, bool bFixedSize=true, int nMaxCountHint=1)
 Add a data member to the message. More...

status_t AddMessage (const char *pzName, const Message *pcVal)
 Add another message object as a member of this message. More...

status_t AddPointer (const char *pzName, const void *pVal)
 Add a pointer to the message. More...

status_t AddInt8 (const char *pzName, int8 nVal)
 Add a 8-bit integer to the message. More...

status_t AddInt16 (const char *pzName, int16 nVal)
 Add a 16-bit integer to the message. More...

status_t AddInt32 (const char *pzName, int32 nVal)
 Add a 32-bit integer to the message. More...

status_t AddInt64 (const char *pzName, int64 nVal)
 Add a 64-bit integer to the message. More...

status_t AddBool (const char *pzName, bool bVal)
 Add a boolean value to the message. More...

status_t AddFloat (const char *pzName, float vVal)
 Add a float to the message. More...

status_t AddDouble (const char *pzName, double vVal)
 Add a double to the message. More...

status_t AddRect (const char *pzName, const Rect &cVal)
status_t AddIRect (const char *pzName, const IRect &cVal)
status_t AddPoint (const char *pzName, const Point &cVal)
status_t AddIPoint (const char *pzName, const IPoint &cVal)
status_t AddColor32 (const char *pzName, const Color32_s &cVal)
status_t AddString (const char *pzName, const char *pzString)
 Add a string to the message. More...

status_t AddString (const char *pzName, const std::string &cString)
 Add a string to the message. More...

status_t AddVariant (const char *pzName, const Variant &cVal)
status_t FindData (const char *pzName, int nType, const void **ppData, size_t *pnSize, int nIndex=0) const
status_t FindMessage (const char *pzName, Message *ppcVal, int nIndex=0) const
status_t FindPointer (const char *pzName, void **ppVal, int nIndex=0) const
status_t FindInt8 (const char *pzName, int8 *pnVal, int nIndex=0) const
status_t FindInt16 (const char *pzName, int16 *pnVal, int nIndex=0) const
status_t FindInt32 (const char *pzName, int32 *pnVal, int nIndex=0) const
status_t FindInt64 (const char *pzName, int64 *pnVal, int nIndex=0) const
status_t FindBool (const char *pzName, bool *pbVal, int nIndex=0) const
status_t FindFloat (const char *pzName, float *pvVal, int nIndex=0) const
status_t FindDouble (const char *pzName, double *pvVal, int nIndex=0) const
status_t FindRect (const char *pzName, Rect *pcVal, int nIndex=0) const
status_t FindIRect (const char *pzName, IRect *pcVal, int nIndex=0) const
status_t FindPoint (const char *pzName, Point *pcVal, int nIndex=0) const
status_t FindIPoint (const char *pzName, IPoint *pcVal, int nIndex=0) const
status_t FindColor32 (const char *pzName, Color32_s *pcVal, int nIndex=0) const
status_t FindString (const char *pzName, const char **pzString, int nIndex=0) const
status_t FindString (const char *pzName, std::string *pcString, int nIndex=0) const
status_t FindVariant (const char *pzName, Variant *pcVal, int nIndex=0) const
template<class T> status_t FindInt (const char *pzName, T *pnVal, int nIndex=0) const
status_t RemoveData (const char *pzName, int nIndex=0)
 Delete an element from the message. More...

status_t RemoveName (const char *pzName)
 Remove all entries stored under a given name. More...

status_t GetNameInfo (const char *pzName, int *pnType=NULL, int *pnCount=NULL) const
int CountNames (void) const
std::string GetName (int nIndex) const
void MakeEmpty (void)
 Clear the message. More...

bool IsEmpty (void) const
bool WasDelivered (void) const
bool IsSourceWaiting (void) const
bool IsSourceRemote (void) const
Messenger ReturnAddress (void) const
bool IsReply (void) const
status_t SendReply (int nCode, Handler *pcReplyHandler=NULL)
status_t SendReply (Message *pcTheReply, Handler *pcReplyHandler=NULL, uint nTimeOut=~0)
status_t SendReply (int nCode, Message *pcReplyToReply)
status_t SendReply (Message *pcTheReply, Message *pcReplyToReply, int nSendTimOut=~0, int nReplyTimeOut=~0)
Message & operator= (const Message &cOther)
 Copy the content of another message. More...


Friends

class Looper
class MessageQueue
class Messenger
class View


Detailed Description

Description:
The os::Message is the heart of the messaging system in AtheOS. An os::Message is a flexible associative container with a few extra features that makes it suitable for storing messages that should be sendt over a low-level messaging system like the AtheOS message-port API or any other package or stream based communication medium like pipes, TCP, UDP, etc etc.

The message associate each message element with a unique name that is assigned by the sender and that will be used by the receiver to lookup the element and retrieve it's data. Since each elements are recognized by a name instead of it's position within a regular structure it is easy to keep a message protocol forward and backward compatible. Often it will be possible for a receiver to come up with reasonable default values for elements that are missing because the sender is to old and it will simply ignore elements it doesn't know about because the sender is to new.

A message element can either be a single object (an int, float, a rectangel, a undefined data-blob, etc, etc) or an array of objects of the same type. Normally each object added to a message have unique names but it is also possible to add multiple objects under the same name. Each object must then be of the same type and they will be added to an array associated with the name. Individual elements from the array can then be retrieved by specifying an index in addition to the name when looking up an entry in the message.

What distinguish the os::Message most from other associative containers like STL maps beside the possibility to add multiple data-types to a single container is it's ability to convert itself to a flat data-buffer that lend itself for easy transmission over most low-level communication channels. Another message object can then be initialized from this data-buffer to create an excact copy of the message.

See also:
os::Messenger, os::Looper, os::Handler, os::Invoker
Author:
Kurt Skauen ([email protected])


Constructor & Destructor Documentation

Message::Message int nCode = 0
 

Description:
Construct an empty message.
Parameters:
nCode   The message code. This can later be retrieved with GetCode().
Author:
Kurt Skauen ([email protected])

Message::Message const Message & cMsg
 

Description:
Copy the message code and all data members from another message.
Parameters:
cMsg   The message to copy.
Author:
Kurt Skauen ([email protected])

Message::Message const void * pFlattenedData
 

Description:
This constructor can be used to create a "live" message from a data-blob created by os::Message::Flatten().
Note:
If the data-blob is not a valid flattened message the std::invalid_argument exception will be thrown.
Parameters:
pFlattenedData   Pointer to a data-blob created by a previous call to Flatten().
See also:
Flatten(), Unflatten()
Author:
Kurt Skauen ([email protected])

Message::~Message
 

Description:
Free all resources allocated by the message.
Author:
Kurt Skauen ([email protected])


Member Function Documentation

status_t Message::AddBool const char * pzName,
bool bVal
 

Description:
Add a boolean value to the message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
bVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindBool(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddColor32 const char * pzName,
const Color32_s & cVal
 

status_t Message::AddData const char * pzName,
int nType,
const void * pData,
uint32 nSize,
bool bFixedSize = true,
int nMaxCountHint = 1
 

Description:
Add data to the message. The os::Message class is a very flexible data container. Each data-member is associated with a name for later retrival. Multiple data elements of the same type can be arranged as an array associated with a single name.

AddData() is a "catch all" function that can be used to add an untyped blob of data to the message. Normally you will use one of the other Add*() member that add a specificly typed data member but I will describe the general principle of adding member to a message here.

When you add a member to a message you must give it a unique name that will later be used to lookup that member. It is possible to add multiple elements with the same name but they must then be of the same type and subsequent elements will be appended to an array associated with this name. Individual elements from the array can later be destined with the name/index pair passed to the various Get*() members.

Note:
The data buffer are copyed into the message and you retain ownership over it.
Parameters:
pzName   The name used to identify the member. If there already exist a member with this name in the message the new member will be appended to an array of elements under this name. It is an error to append objects with different types under the same name.
nType   Data type. This should be one of the predefined type codes. Normally you should only use this member to add T_RAW type data. All the more specific data-types should be added with one of the specialized Add*() members.
pData   Pointer to the data to be add. The data will be copyed into the message.
nSize   Size of the pData buffer.
bFixedSize   If you plan to make an array of members under the same name you must let the message know if each element can have a different size. If the message know that all the elements have the same size it can optimize the data a bit by only storing the size once. It will also greatly speed up array-element lookups if each element have the same size. If all elements in an array will have the same size or if you plan to add only one member under this name bFixedSize should be true. Otherwhice it should be false.
nMaxCountHint   An estimate of how many members are going to be added to this array. If you plan to add many elements under the same name and you know up-front how many you are going to add it is a good idea to let the message know when adding the first element. The nMaxCountHint will be used to decide how much memory to be allocated for the array and if the estimate is correct it will avoid any expensive reallocations during element insertions.
Returns:
On success 0 is returned. On error -1 is returned an an error code is written to the global variable errno.
See also:
FindData(), RemoveData(), RemoveName(), GetNameInfo()
Author:
Kurt Skauen ([email protected])

status_t Message::AddDouble const char * pzName,
double vVal
 

Description:
Add a double to the message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
vVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindDouble(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddFloat const char * pzName,
float vVal
 

Description:
Add a float to the message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
vVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindFloat(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddIPoint const char * pzName,
const IPoint & cVal
 

status_t Message::AddIRect const char * pzName,
const IRect & cVal
 

status_t Message::AddInt16 const char * pzName,
int16 nVal
 

Description:
Add a 16-bit integer to the message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
nVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindInt16(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddInt32 const char * pzName,
int32 nVal
 

Description:
Add a 32-bit integer to the message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
nVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindInt32(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddInt64 const char * pzName,
int64 nVal
 

Description:
Add a 64-bit integer to the message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
nVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindInt64(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddInt8 const char * pzName,
int8 nVal
 

Description:
Add a 8-bit integer to the message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
nVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindInt8(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddMessage const char * pzName,
const Message * pcVal
 

Description:
Add another message object as a member of this message.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
pcVal   The object to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindMessage(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddPoint const char * pzName,
const Point & cVal
 

status_t Message::AddPointer const char * pzName,
const void * pVal
 

Description:
Add a pointer to the message. Only the pointer itself will be stored not the data it is pointing to. This means that you can not send the message to another process and access the pointer there. You must also be careful not to delete the object the pointer referre to before the receiver of the message is done using it.

Set AddData() for more details on how to add members to the message.

Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
pVal   The pointer you want to add. Only the value of the pointer will be stored. Not the object it is pointing at.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindPointer(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddRect const char * pzName,
const Rect & cVal
 

status_t Message::AddString const char * pzName,
const std::string & cString
 

Description:
Add a STL string to the message.

Set AddData() for more details on how to add members to the message.

Note:
The two string types (old fashion C-string and STL strings) are fully interchangable. They are stored the same way internally so it does not matter which member it was added with or what member it is retrieved with. You can add it as an C-string and look it up again as an STL string.
Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
cString   The string to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindString(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddString const char * pzName,
const char * pzString
 

Description:
Add a string to the message. The string must be NUL terminated and will be copyed into the message.

Set AddData() for more details on how to add members to the message.

Note:
The two string types (old fashion C-string and STL strings) are fully interchangable. They are stored the same way internally so it does not matter which member it was added with or what member it is retrieved with. You can add it as an C-string and look it up again as an STL string.
Parameters:
pzName   A name uniquely identifying the added object within the message. It is possible to add multiple objects of the same type under the same name but it is an error to use the same name for two objects of different type.
pzString   The string to add.
Returns:
On success 0 is returned. On failure -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOMEM Not enough memory to expand the message.
See also:
FindString(), AddData(), FindData()
Author:
Kurt Skauen ([email protected])

status_t Message::AddVariant const char * pzName,
const Variant & cVal
 

int Message::CountNames void const
 

status_t Message::FindBool const char * pzName,
bool * pbVal,
int nIndex = 0
const
 

status_t Message::FindColor32 const char * pzName,
Color32_s * pcVal,
int nIndex = 0
const
 

status_t Message::FindData const char * pzName,
int nType,
const void ** ppData,
size_t * pnSize,
int nIndex = 0
const
 

status_t Message::FindDouble const char * pzName,
double * pvVal,
int nIndex = 0
const
 

status_t Message::FindFloat const char * pzName,
float * pvVal,
int nIndex = 0
const
 

status_t Message::FindIPoint const char * pzName,
IPoint * pcVal,
int nIndex = 0
const
 

status_t Message::FindIRect const char * pzName,
IRect * pcVal,
int nIndex = 0
const
 

template<class T>
status_t os::Message::FindInt const char * pzName,
T * pnVal,
int nIndex = 0
const [inline]
 

status_t Message::FindInt16 const char * pzName,
int16 * pnVal,
int nIndex = 0
const
 

status_t Message::FindInt32 const char * pzName,
int32 * pnVal,
int nIndex = 0
const
 

status_t Message::FindInt64 const char * pzName,
int64 * pnVal,
int nIndex = 0
const
 

status_t Message::FindInt8 const char * pzName,
int8 * pnVal,
int nIndex = 0
const
 

status_t Message::FindMessage const char * pzName,
Message * pcVal,
int nIndex = 0
const
 

status_t Message::FindPoint const char * pzName,
Point * pcVal,
int nIndex = 0
const
 

status_t Message::FindPointer const char * pzName,
void ** ppVal,
int nIndex = 0
const
 

status_t Message::FindRect const char * pzName,
Rect * pcVal,
int nIndex = 0
const
 

status_t Message::FindString const char * pzName,
std::string * pcString,
int nIndex = 0
const
 

status_t Message::FindString const char * pzName,
const char ** ppzString,
int nIndex = 0
const
 

status_t Message::FindVariant const char * pzName,
Variant * pcVal,
int nIndex = 0
const
 

status_t Message::Flatten uint8 * pBuffer,
size_t nSize
const
 

Description:
Flatten() will convert the message into a flat data-stream that lend itself well for transmission over the lowlevel message system to other processes or for storing a message on disk for later retrival.

All the data members, the message code, and any additional data might needed to reconstruct the exact same message are written to the buffer in a format understod by the Unflatten() member and the Message::Message(void*) constructor.

Note:
To learn how large the pBuffer must be you must first call GetFlattenedSize().
Parameters:
pBuffer   Pointer to a buffer at least as large as reported by GetFlattenedSize() where the flattened message will be written.
nSize   Size of the buffer passed as pBuffer
Returns:
On success 0 is returned. If the buffer is to small -1 is returned and the global variable errno is set to EOVERFLOW.
See also:
GetFlattenedSize(), Unflatten()
Author:
Kurt Skauen ([email protected])

int os::Message::GetCode void const [inline]
 

size_t Message::GetFlattenedSize void const
 

Description:
Call this member to learn how large buffer must be allocated before calling Flatten().
Returns:
The number of bytes needed to flatten this message.
See also:
Flatten(), Unflatten()
Author:
Kurt Skauen ([email protected])

std::string Message::GetName int nIndex const
 

status_t Message::GetNameInfo const char * pzName,
int * pnType = NULL,
int * pnCount = NULL
const
 

bool Message::IsEmpty void const
 

bool Message::IsReply void const
 

bool Message::IsSourceRemote void const
 

bool Message::IsSourceWaiting void const
 

void Message::MakeEmpty void
 

Description:
Clear the message and delete all datamembers. The message code will not be modified.
Author:
Kurt Skauen ([email protected])

status_t Message::RemoveData const char * pzName,
int nIndex = 0
 

Description:
Delete a single element from a message member.
Parameters:
pzName   The member name.
nIndex   Index of the element to delete. If more than one element was added under the same name you can select which one to delete with this index.
Returns:
On success 0 is returned. If the name was not found or the index was out of range -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOENT The name was not found.
EINVAL The index was out of range.
See also:
RemoveName(),AddData()
Author:
Kurt Skauen ([email protected])

status_t Message::RemoveName const char * pzName
 

Description:
Delete all entries stored under a given name.
Parameters:
pzName   The name of the member to delete.
Returns:
On success 0 is returned. If the name was not found -1 is returned and a error code is written to the global variable errno.
Error codes:
ENOENT The name was not found.
See also:
RemoveData(), AddData()
Author:
Kurt Skauen ([email protected])

Messenger Message::ReturnAddress void const
 

status_t Message::SendReply Message * pcTheReply,
Message * pcReplyToReply,
int nSendTimOut = ~0,
int nReplyTimeOut = ~0
 

status_t Message::SendReply int nCode,
Message * pcReplyToReply
 

status_t Message::SendReply Message * pcTheReply,
Handler * pcReplyHandler = NULL,
uint nTimeOut = ~0
 

status_t Message::SendReply int nCode,
Handler * pcReplyHandler = NULL
 

void os::Message::SetCode int nCode [inline]
 

status_t Message::Unflatten const uint8 * pBuffer
 

Description:
Unflatten() can reconstruct a message previously flattened with the Flatten() member.

This will reconstruct an excact copy of the message that was used to create the data-blob.

Note:
The previous content of the message will be discarded.
Parameters:
pBuffer   Pointer to a data-blob previously created with Flatten()
Returns:
On success 0 is returned. If the data-blob is not a valid flattened message -1 is returned and the global variable errno is et to EINVAL.
See also:
Flatten(), Message::Message(void*)
Author:
Kurt Skauen ([email protected])

bool Message::WasDelivered void const
 

Message & Message::operator= const Message & cMsg
 

Description:
The assignment operator will copy the message code and all data members from cMsg
Parameters:
cMsg   The message to copy.
Returns:
A reference to the message itself.
Author:
Kurt Skauen ([email protected])


Friends And Related Function Documentation

friend class Looper [friend]
 

friend class MessageQueue [friend]
 

friend class Messenger [friend]
 

friend class View [friend]
 


Generated at Tue Sep 11 15:27:51 2001 for AtheOS higlevel API by doxygen1.2.9.1 written by Dimitri van Heesch, © 1997-2001