os::Message Class Reference

Inheritance diagram for os::Message:

Public Member Functions
	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	AddObject (const char *pzName, const Flattenable &cVal)
	Add an object as a member of this 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	AddString (const char *pzName, const String &cString)
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	FindObject (const char *pzName, Flattenable &cVal, 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	FindString (const char *pzName, 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
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
class	Settings

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@.nosp@m.athe.nosp@m.os.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@.nosp@m.athe.nosp@m.os.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@.nosp@m.athe.nosp@m.os.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@.nosp@m.athe.nosp@m.os.cx)

References Unflatten().

Message::~Message

(

)

Description:

Free all resources allocated by the message.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

References MakeEmpty().

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_BOOL.

Referenced by os::TreeView::Collapse(), os::TreeView::Expand(), os::DropdownMenu::HandleMessage(), os::Translator::Invoke(), os::CheckMenu::Invoked(), os::ScrollBar::Invoked(), os::TextView::Invoked(), os::Slider::Invoked(), os::DropdownMenu::DropdownView::KeyDown(), os::Window::MakeFocus(), os::DropdownMenu::DropdownView::MouseDown(), os::DropdownMenu::DropdownView::MouseUp(), MoveFileThread(), os::RegistrarManager::RegisterType(), os::RegistrarManager::RegisterTypeIcon(), os::AppserverConfig::SetPopoupSelectedWindows(), os::DropdownMenu::SetSelection(), os::TreeViewCheckNode::Toggle(), os::CheckRow::Toggle(), and os::RegistrarManager::~RegistrarManager().

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

References AddData(), and os::T_COLOR32.

Referenced by os::Application::CommitColorConfig(), and os::ColorRequester::HandleMessage().

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@.nosp@m.athe.nosp@m.os.cx)

Referenced by AddBool(), AddColor32(), AddDouble(), AddFloat(), AddInt16(), AddInt32(), AddInt64(), AddInt8(), AddIPoint(), AddIRect(), AddPoint(), AddPointer(), AddRect(), AddString(), os::Translator::Invoke(), os::Application::PushCursor(), and os::Settings::SetData().

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_DOUBLE.

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_FLOAT.

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_INT16.

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_INT32.

Referenced by os::DropdownMenu::DropdownView::Activated(), os::Application::Application(), os::View::BeginDrag(), os::TabView::DeleteTab(), os::Application::GetScreenModeInfo(), os::Font::GetSupportedCharacters(), os::RegistrarManager::GetType(), os::IconView::Private::GetViewFrame(), os::DropdownMenu::HandleMessage(), os::Alert::HandleMessage(), os::Translator::Invoke(), os::TextView::Invoked(), os::DropdownMenu::DropdownView::KeyDown(), os::Desktop::MinimizeAll(), os::DropdownMenu::DropdownView::MouseDown(), os::DropdownMenu::DropdownView::MouseMove(), os::DropdownMenu::DropdownView::MouseUp(), os::Event::PostEvent(), os::Application::PushCursor(), os::Font::SetFamilyAndStyle(), os::Window::SetFlags(), os::Window::SetIcon(), os::Application::SetKeyboardTimings(), os::DropdownMenu::SetSelection(), os::TabView::SetSelection(), and os::View::ToggleDepth().

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_INT64.

Referenced by os::RegistrarManager::ClearTypeExtensions(), os::RegistrarManager::ClearTypeHandlers(), os::Event::GetLastEventMessage(), os::RegistrarManager::GetType(), os::RegistrarManager::GetTypeAndIcon(), os::RegistrarManager::GetTypeCount(), os::Event::PostEvent(), os::RegistrarManager::RegisterType(), os::RegistrarManager::RegisterTypeExtension(), os::RegistrarManager::RegisterTypeHandler(), os::RegistrarManager::RegisterTypeIcon(), os::RegistrarManager::RegistrarManager(), os::RegistrarManager::SetDefaultHandler(), os::AppserverConfig::SetDoubleClickTime(), os::AppserverConfig::SetKeyDelay(), os::AppserverConfig::SetKeyRepeat(), os::Event::SetMonitorEnabled(), os::Event::SetToRemote(), os::RegistrarManager::UnregisterType(), os::Event::~Event(), and os::RegistrarManager::~RegistrarManager().

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_INT8.

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

References AddData(), and os::T_IPOINT.

Referenced by os::Application::PushCursor(), and os::Window::SetAlignment().

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

References AddData(), and os::T_IRECT.

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@.nosp@m.athe.nosp@m.os.cx)

References Flatten(), GetFlattenedSize(), and os::T_MESSAGE.

Referenced by os::View::BeginDrag(), os::Event::PostEvent(), and os::Settings::SetMessage().

status_t Message::AddObject	(	const char *	pzName,
		const Flattenable &	cVal
	)

Description:

Add a flattenable object as a member of this message.

See 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

FindObject(), AddData(), FindData()

Author

Henrik Isaksson

References os::Flattenable::Flatten(), os::Flattenable::GetFlattenedSize(), and os::Flattenable::GetType().

Referenced by os::DateView::HandleMessage(), os::CalendarView::HandleMessage(), os::Application::RegisterKeyEvent(), os::Application::UnregisterKeyEvent(), and os::Application::~Application().

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

References AddData(), and os::T_POINT.

Referenced by os::View::BeginDrag(), os::IconDirectoryView::DragSelection(), os::RegistrarManager::GetTypeAndIcon(), os::View::SetMousePos(), os::Window::SetSizeLimits(), and os::DropdownMenu::WheelMoved().

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_POINTER.

Referenced by os::TreeView::Collapse(), os::TreeView::Expand(), os::FileRequester::HandleMessage(), os::ColorRequester::HandleMessage(), os::InputBox::HandleMessage(), os::Invoker::Invoke(), os::FileRequester::OkToQuit(), os::ColorRequester::OkToQuit(), os::InputBox::OkToQuit(), os::TreeViewCheckNode::Toggle(), os::CheckRow::Toggle(), and os::DropdownMenu::WheelMoved().

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

References AddData(), and os::T_RECT.

Referenced by os::View::BeginDrag().

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_STRING.

Referenced by os::Application::Application(), os::RegistrarManager::ClearTypeExtensions(), os::RegistrarManager::ClearTypeHandlers(), os::IconDirectoryView::DirChanged(), os::IconDirectoryView::DragSelection(), os::RegistrarManager::GetAppList(), os::Font::GetBitmapSizes(), os::Event::GetLastEventMessage(), os::TextEdit::GetRegion(), os::Event::GetRemoteChildren(), os::RegistrarManager::GetType(), os::RegistrarManager::GetTypeAndIcon(), os::RegistrarManager::GetTypeCount(), os::FileRequester::HandleMessage(), os::Event::PostEvent(), os::Application::RegisterKeyEvent(), os::RegistrarManager::RegisterType(), os::RegistrarManager::RegisterTypeExtension(), os::RegistrarManager::RegisterTypeHandler(), os::RegistrarManager::RegisterTypeIcon(), os::RegistrarManager::RegistrarManager(), os::IconDirectoryView::ReRead(), os::RegistrarManager::SetDefaultHandler(), os::Font::SetFamilyAndStyle(), os::Application::SetKeymap(), os::Event::SetMonitorEnabled(), os::Window::SetTitle(), os::Event::SetToRemote(), os::Application::UnregisterKeyEvent(), os::RegistrarManager::UnregisterType(), os::RegistrarManager::UpdateAppList(), os::Application::~Application(), os::Event::~Event(), and os::RegistrarManager::~RegistrarManager().

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@.nosp@m.athe.nosp@m.os.cx)

References AddData(), and os::T_STRING.

status_t Message::AddString	(	const char *	pzName,
		const String &	cString
	)

References AddData(), os::String::c_str(), os::String::size(), and os::T_STRING.

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

References os::Variant::Flatten(), os::Variant::GetFlattenedSize(), and os::T_VARIANT.

Referenced by os::InputBox::HandleMessage(), os::Control::Invoked(), and os::Settings::SetVariant().

int Message::CountNames

(

void

)

const

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

References FIRST_CHUNK, and os::T_BOOL.

Referenced by os::Window::DispatchMessage(), os::Settings::GetBool(), os::AppserverConfig::GetPopoupSelectedWindows(), os::Font::GetSupportedCharacters(), os::DropdownMenu::HandleMessage(), os::IconDirectoryView::HandleMessage(), os::IconDirectoryView::IconDirectoryView(), and os::Font::Rescan().

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

References FIRST_CHUNK, and os::T_COLOR32.

Referenced by os::Application::Application(), os::BitmapImage::ApplyFilter(), os::Settings::GetColor32(), and os::Application::HandleMessage().

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

References CHUNK_DATA.

Referenced by FindMessage(), FindObject(), FindString(), FindVariant(), and os::IconDirectoryView::HandleMessage().

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

References FIRST_CHUNK, and os::T_DOUBLE.

Referenced by os::Settings::GetDouble().

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

References FIRST_CHUNK, and os::T_FLOAT.

Referenced by os::Desktop::Desktop(), os::Font::GetBitmapSizes(), os::Settings::GetFloat(), and os::Application::GetScreenModeInfo().

template<class T >

status_t os::Message::FindInt ( const char *  pzName, T *  pnVal, int  nIndex = 0  ) const

inline

Referenced by os::Application::Application(), os::Desktop::Desktop(), os::Font::GetBitmapSizes(), os::Application::GetKeyboardConfig(), os::View::GetMouse(), os::Application::GetScreenModeCount(), os::Application::GetScreenModeInfo(), os::Font::GetSupportedCharacters(), os_priv::DirKeeper::HandleMessage(), os::IconDirectoryView::HandleMessage(), and os::Font::SetFamilyAndStyle().

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

References FIRST_CHUNK, and os::T_INT16.

Referenced by os::Settings::GetInt16().

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

References FIRST_CHUNK, and os::T_INT32.

Referenced by os::BitmapImage::ApplyFilter(), os::Desktop::Desktop(), os::Window::DispatchMessage(), os::RegistrarAppList::GetCount(), os::Application::GetCurrentKeyShortcuts(), os::RegistrarFileType::GetExtensionCount(), os::RegistrarFileType::GetHandlerCount(), os::Settings::GetInt32(), os::Font::GetSupportedCharacters(), os::RegistrarManager::GetTypeCount(), os::CalendarView::HandleMessage(), os::FileRequester::HandleMessage(), os::DropdownMenu::HandleMessage(), os_priv::DirKeeper::HandleMessage(), HandlerSelector::HandlerSelector(), os::IconDirectoryView::KeyDown(), and os::Desktop::MinimizeAll().

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

References FIRST_CHUNK, and os::T_INT64.

Referenced by os::AppserverConfig::GetDoubleClickTime(), os::Application::GetIdleTime(), os::Settings::GetInt64(), os::AppserverConfig::GetKeyDelay(), os::AppserverConfig::GetKeyRepeat(), os_priv::DirKeeper::HandleMessage(), os::IconDirectoryView::HandleMessage(), and os::Event::SetToRemote().

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

References FIRST_CHUNK, and os::T_INT8.

Referenced by os::Settings::GetInt8().

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

References FIRST_CHUNK, os::T_ANY_TYPE, os::T_IPOINT, and os::T_POINT.

Referenced by os::Desktop::Desktop(), os::Window::DispatchMessage(), os::Settings::GetIPoint(), and os::Application::GetScreenModeInfo().

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

References FIRST_CHUNK, os::T_ANY_TYPE, os::T_IRECT, and os::T_RECT.

Referenced by os::Settings::GetIRect().

status_t Message::FindMessage	(	const char *	pzName,
		Message *	ppcVal,
		int	nIndex = 0
	)		const

References FindData(), os::T_MESSAGE, and Unflatten().

Referenced by os::Window::DispatchMessage().

status_t Message::FindObject	(	const char *	pzName,
		Flattenable &	cVal,
		int	nIndex = 0
	)		const

References FindData(), os::Flattenable::GetType(), and os::Flattenable::Unflatten().

Referenced by os::Application::GetCurrentKeyShortcuts().

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

References FIRST_CHUNK, os::T_ANY_TYPE, os::T_IPOINT, and os::T_POINT.

Referenced by os::Window::DispatchMessage(), os::View::GetMouse(), os::Settings::GetPoint(), and os::IconDirectoryView::MouseUp().

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

References FIRST_CHUNK, and os::T_POINTER.

Referenced by os::Window::DispatchMessage(), and os::IconDirectoryView::HandleMessage().

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

References FIRST_CHUNK, os::T_ANY_TYPE, os::T_IRECT, and os::T_RECT.

Referenced by os::Window::DispatchMessage(), os::Settings::GetRect(), and os::IconView::Private::GetViewFrame().

status_t Message::FindString	(	const char *	pzName,
		const char **	pzString,
		int	nIndex = 0
	)		const

References FindData(), and os::T_STRING.

Referenced by os::Window::DispatchMessage(), os::RegistrarAppList::GetCategory(), os::Application::GetCurrentKeyShortcuts(), os::RegistrarFileType::GetDefaultHandler(), os::RegistrarFileType::GetExtension(), os::RegistrarFileType::GetHandler(), os::RegistrarFileType::GetIcon(), os::RegistrarFileType::GetIdentifier(), os::Application::GetKeyboardConfig(), os::RegistrarFileType::GetMimeType(), os::RegistrarAppList::GetName(), os::RegistrarAppList::GetPath(), os::Event::GetRemoteChildren(), os::Settings::GetString(), os::RegistrarManager::GetTypeAndIcon(), os::TextEdit::HandleKeyDown(), os_priv::DirKeeper::HandleMessage(), os::IconDirectoryView::HandleMessage(), InfoWin::HandleMessage(), HandlerSelector::HandlerSelector(), InfoWin::InfoWin(), os::Locale::Private::Init(), os::RegistrarManager::Launch(), os::IconDirectoryView::MouseMove(), os::IconDirectoryView::MouseUp(), os::TextView::Paste(), and os::Event::SetToRemote().

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

References FindData(), and os::T_STRING.

status_t Message::FindString	(	const char *	pzName,
		String *	pcString,
		int	nIndex = 0
	)		const

References FindData(), and os::T_STRING.

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

References FindData(), os::T_VARIANT, and os::Variant::Unflatten().

Referenced by os::Settings::GetVariant().

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@.nosp@m.athe.nosp@m.os.cx)

Referenced by AddMessage(), os::Clipboard::Commit(), os::Settings::Save(), os::Settings::SetMessage(), and os::Variant::Variant().

int os::Message::GetCode ( void  ) const

inline

Referenced by os::BitmapImage::ApplyFilter(), os::RegistrarManager::ClearTypeExtensions(), os::RegistrarManager::ClearTypeHandlers(), os::Looper::DispatchMessage(), os::Window::DispatchMessage(), os::MessageFilter::Filter(), os::Menu::FindItem(), os::MessageQueue::FindMessage(), os::Invoker::GetCode(), os::Event::GetRemoteChildren(), os::RegistrarManager::GetType(), os::RegistrarManager::GetTypeAndIcon(), os::RegistrarManager::GetTypeCount(), os::DateView::HandleMessage(), os::CalendarView::HandleMessage(), os::DropdownMenu::DropdownView::HandleMessage(), os::FileRequester::HandleMessage(), os::ColorRequester::HandleMessage(), os::Spinner::HandleMessage(), os::Application::HandleMessage(), os::DropdownMenu::HandleMessage(), os::InputBox::HandleMessage(), os_priv::DirKeeper::HandleMessage(), os::Alert::HandleMessage(), os::IconDirectoryView::HandleMessage(), NewDirWin::HandleMessage(), RenameFileWin::HandleMessage(), os::ProgressRequester::HandleMessage(), MountDialogWin::HandleMessage(), InfoWin::HandleMessage(), HandlerSelector::HandleMessage(), os::RegistrarManager::RegisterType(), os::RegistrarManager::RegisterTypeExtension(), os::RegistrarManager::RegisterTypeHandler(), os::RegistrarManager::RegisterTypeIcon(), os::RegistrarManager::RegistrarManager(), os::IconDirectoryView::ReRead(), os::RegistrarManager::SetDefaultHandler(), os::Event::SetToRemote(), os_priv::DirKeeper::Stop(), and os::RegistrarManager::UnregisterType().

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@.nosp@m.athe.nosp@m.os.cx)

Referenced by AddMessage(), os::Clipboard::Commit(), os::Settings::Save(), os::Settings::SetMessage(), and os::Variant::Variant().

String Message::GetName

(

int

nIndex

)

const

References ARRAY_NAME.

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

References os::T_ANY_TYPE.

Referenced by os::Locale::Private::Init().

bool Message::IsEmpty

(

void

)

const

bool Message::IsReply

(

void

)

const

bool Message::IsSourceRemote

(

void

)

const

bool Message::IsSourceWaiting

(

void

)

const

References WasDelivered().

Referenced by SendReply().

void Message::MakeEmpty

(

void

)

Description:

Clear the message and delete all datamembers. The message code will not be modified.

Author

Kurt Skauen (kurt@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::Clipboard::GetData(), Unflatten(), os::Clipboard::Unlock(), and ~Message().

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@.nosp@m.athe.nosp@m.os.cx)

Referenced by os::Settings::operator=().

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@.nosp@m.athe.nosp@m.os.cx)

References FIRST_CHUNK, and os::T_ANY_TYPE.

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@.nosp@m.athe.nosp@m.os.cx)

References os::T_ANY_TYPE.

Referenced by os::AppserverConfig::SetDoubleClickTime(), os::AppserverConfig::SetKeyDelay(), os::AppserverConfig::SetKeyRepeat(), and os::AppserverConfig::SetPopoupSelectedWindows().

Messenger Message::ReturnAddress

(

void

)

const

References Messenger.

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

Referenced by SendReply().

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

References os::Handler::GetLooper(), os::Looper::GetMsgPort(), os::Looper::GetThread(), and IsSourceWaiting().

status_t Message::SendReply	(	int	nCode,
		Message *	pcReplyToReply
	)

References SendReply().

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

References IsSourceWaiting().

void os::Message::SetCode ( int  nCode )

inline

Referenced by os::AppserverConfig::Commit(), and os::Event::PostEvent().

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@.nosp@m.athe.nosp@m.os.cx)

References MakeEmpty().

Referenced by FindMessage(), os::Clipboard::GetData(), os::Settings::Load(), and Message().

bool Message::WasDelivered

(

void

)

const

Referenced by IsSourceWaiting().

Friends And Related Function Documentation

friend class Looper

friend

friend class MessageQueue

friend

friend class Messenger

friend

Referenced by ReturnAddress().

friend class Settings

friend

friend class View

friend