---

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 (kurt@atheos.cx)

---

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

Message::~Message (  )

Description: Free all resources allocated by the message. Author: Kurt Skauen (kurt@atheos.cx)

---

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

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 (kurt@atheos.cx)

---

Friends And Related Function Documentation

friend class Looper [friend]

friend class MessageQueue [friend]

friend class Messenger [friend]

friend class View [friend]

---