• 
• 
• 
• 

BMessage Class Reference
[Application Kit]

A container that can be send and received using the Haiku messaging subsystem. More...

List of all members.

Public Member Functions
	BMessage (const BMessage &other)
	Construct a new message that is a copy of another message.
	BMessage (uint32 what)
	Construct an empty message with the what member set tot the specified value.
	BMessage ()
	Construct an empty message, without any data members and with a what constant set to zero (0).
BMessage &	operator= (const BMessage &other)
	Copy one message into another.
virtual	~BMessage ()
	Free the data members associated with the message.
Adding Data
status_t	AddBool (const char *name, bool aBoolean)
	Convenience method to add a bool to the label name.
status_t	AddData (const char *name, type_code type, const void *data, ssize_t numBytes, bool isFixedSize=true, int32 count=1)
	Add data of a certain type to the message.
status_t	AddDouble (const char *name, double aDouble)
	Convenience method to add a double to the label name.
status_t	AddFlat (const char *name, BFlattenable *object, int32 count=1)
	Convenience method to add a flattenable to the label name.
status_t	AddFloat (const char *name, float aFloat)
	Convenience method to add a float to the label name.
status_t	AddInt16 (const char *name, int16 value)
	Convenience method to add an int16 to the label name.
status_t	AddInt32 (const char *name, int32 value)
	Convenience method to add an int32 to the label name.
status_t	AddInt64 (const char *name, int64 value)
	Convenience method to add an int64 to the label name.
status_t	AddInt8 (const char *name, int8 value)
	Convenience method to add an int8 to the label name.
status_t	AddMessage (const char *name, const BMessage *message)
	Convenience method to add a message to the label name.
status_t	AddMessenger (const char *name, BMessenger messenger)
	Convenience method to add a messenger to the label name.
status_t	AddPoint (const char *name, BPoint aPoint)
	Convenience method to add a BPoint to the label name.
status_t	AddPointer (const char *name, const void *aPointer)
	Convenience method to add a pointer to the label name.
status_t	AddRect (const char *name, BRect aRect)
	Convenience method to add a BRect to the label name.
status_t	AddRef (const char *name, const entry_ref *ref)
	Convenience method to add an entry_ref to the label name.
status_t	AddString (const char *name, const BString &aString)
	Convenience method to add a BString to the label name.
status_t	AddString (const char *name, const char *aString)
	Convenience method to add a C-string to the label name.
Specifiers (Scripting)
status_t	AddSpecifier (const BMessage *specifier)
	Undocumented.
status_t	AddSpecifier (const char *property, const char *name)
	Undocumented.
status_t	AddSpecifier (const char *property, int32 index, int32 range)
	Undocumented.
status_t	AddSpecifier (const char *property, int32 index)
	Undocumented.
status_t	AddSpecifier (const char *property)
	Undocumented.
status_t	GetCurrentSpecifier (int32 *index, BMessage *specifier=NULL, int32 *what=NULL, const char **property=NULL) const
	Undocumented.
bool	HasSpecifiers () const
	Undocumented.
status_t	PopSpecifier ()
	Undocumented.
status_t	SetCurrentSpecifier (int32 index)
	Undocumented.
Statistics and Miscelanous Information
int32	CountNames (type_code type) const
	Count the number of names of a certain type.
status_t	GetInfo (const char *name, type_code *typeFound, bool *fixedSize) const
	Retrieve the type and whether or not the size of the data is fixed associated with a name.
status_t	GetInfo (const char *name, type_code *typeFound, int32 *countFound=NULL) const
	Retrieve the type and the number of data items in this message that are associated with a name.
status_t	GetInfo (type_code typeRequested, int32 index, char **nameFound, type_code *typeFound, int32 *countFound=NULL) const
	Retrieve the name, the type and the number of items in a message by an index.
bool	IsEmpty () const
	Check if the message has data members.
bool	IsReply () const
	Check if the message is a reply to a (previous) message.
bool	IsSystem () const
	Check if the message is a system message.
void	PrintToStream () const
	Print the message to the standard output.
status_t	Rename (const char *oldEntry, const char *newEntry)
	Rename a data label.
Delivery Info
BPoint	DropPoint (BPoint *offset=NULL) const
	Get the coordinates of the drop point of the message.
bool	IsSourceRemote () const
	Check if the message is sent by another application.
bool	IsSourceWaiting () const
	Check if the sender expects a reply.
const BMessage *	Previous () const
	Get the message to which this message is a reply.
BMessenger	ReturnAddress () const
	Get a messenger that points to the sender of the message.
bool	WasDelivered () const
	Check if this message was delivered through the delivery methods.
bool	WasDropped () const
	Check if the message was delivered through 'drag and drop'.
Deprecated methods
These methods are very likely to disappear, and they have been replaced by safer and more powerful methods. These methods are still implemented for binary compatibility, but they are not documented.
bool	FindBool (const char *, int32 n=0) const
	Deprecated.
double	FindDouble (const char *, int32 n=0) const
	Deprecated.
float	FindFloat (const char *, int32 n=0) const
	Deprecated.
int16	FindInt16 (const char *, int32 n=0) const
	Deprecated.
int32	FindInt32 (const char *, int32 n=0) const
	Deprecated.
int64	FindInt64 (const char *, int32 n=0) const
	Deprecated.
int8	FindInt8 (const char *, int32 n=0) const
	Deprecated.
BPoint	FindPoint (const char *, int32 n=0) const
	Deprecated.
BRect	FindRect (const char *, int32 n=0) const
	Deprecated.
const char *	FindString (const char *, int32 n=0) const
	Deprecated.
bool	HasBool (const char *, int32 n=0) const
	Deprecated.
bool	HasData (const char *, type_code, int32 n=0) const
	Deprecated.
bool	HasDouble (const char *, int32 n=0) const
	Deprecated.
bool	HasFlat (const char *, int32 n, const BFlattenable *) const
	Deprecated.
bool	HasFlat (const char *, const BFlattenable *) const
	Deprecated.
bool	HasFloat (const char *, int32 n=0) const
	Deprecated.
bool	HasInt16 (const char *, int32 n=0) const
	Deprecated.
bool	HasInt32 (const char *, int32 n=0) const
	Deprecated.
bool	HasInt64 (const char *, int32 n=0) const
	Deprecated.
bool	HasInt8 (const char *, int32 n=0) const
	Deprecated.
bool	HasMessage (const char *, int32 n=0) const
	Deprecated.
bool	HasMessenger (const char *, int32 n=0) const
	Deprecated.
bool	HasPoint (const char *, int32 n=0) const
	Deprecated.
bool	HasPointer (const char *, int32 n=0) const
	Deprecated.
bool	HasRect (const char *, int32 n=0) const
	Deprecated.
bool	HasRef (const char *, int32 n=0) const
	Deprecated.
bool	HasString (const char *, int32 n=0) const
	Deprecated.
void	operator delete (void *pointer, size_t size)
	Internal operator.
void *	operator new (size_t, void *pointer)
	Internal operator.
void *	operator new (size_t size)
	Internal operator.
Finding Data
Look at FindData() for a general introduction to finding data.
status_t	FindBool (const char *name, int32 index, bool *value) const
	Find a boolean at the label name at an index.
status_t	FindBool (const char *name, bool *value) const
	Find a boolean at the label name.
status_t	FindData (const char *name, type_code type, int32 index, const void **data, ssize_t *numBytes) const
	Find data that is stored in this message at an index.
status_t	FindData (const char *name, type_code type, const void **data, ssize_t *numBytes) const
	Find data that is stored in this message.
status_t	FindDouble (const char *name, int32 index, double *value) const
	Find a double at the label name at an index.
status_t	FindDouble (const char *name, double *value) const
	Find a double at the label name.
status_t	FindFlat (const char *name, int32 index, BFlattenable *object) const
	Find a flattened object at the label name at an index.
status_t	FindFlat (const char *name, BFlattenable *object) const
	Find a flattened object at the label name.
status_t	FindFloat (const char *name, int32 index, float *value) const
	Find a float at the label name at an index.
status_t	FindFloat (const char *name, float *value) const
	Find a float at the label name.
status_t	FindInt16 (const char *name, int32 index, int16 *value) const
	Find an integer at the label name at an index.
status_t	FindInt16 (const char *name, int16 *value) const
	Find an integer at the label name.
status_t	FindInt32 (const char *name, int32 index, int32 *value) const
	Find an integer at the label name at an index.
status_t	FindInt32 (const char *name, int32 *value) const
	Find an integer at the label name.
status_t	FindInt64 (const char *name, int32 index, int64 *value) const
	Find an integer at the label name at an index.
status_t	FindInt64 (const char *name, int64 *value) const
	Find an integer at the label name.
status_t	FindInt8 (const char *name, int32 index, int8 *value) const
	Find an integer at the label name at an index.
status_t	FindInt8 (const char *name, int8 *value) const
	Find an integer at the label name.
status_t	FindMessage (const char *name, int32 index, BMessage *message) const
	Find a message at the label name at an index.
status_t	FindMessage (const char *name, BMessage *message) const
	Find a message at the label name.
status_t	FindMessenger (const char *name, int32 index, BMessenger *messenger) const
	Find a messenger at the label name at an index.
status_t	FindMessenger (const char *name, BMessenger *messenger) const
	Find a messenger at the label name.
status_t	FindPoint (const char *name, int32 index, BPoint *point) const
	Find a point at the label name at an index.
status_t	FindPoint (const char *name, BPoint *point) const
	Find a point at the label name.
status_t	FindPointer (const char *name, int32 index, void **pointer) const
	Find a pointer at the label name at an index.
status_t	FindPointer (const char *name, void **pointer) const
	Find a pointer at the label name.
status_t	FindRect (const char *name, int32 index, BRect *rect) const
	Find a rectangle at the label name at an index.
status_t	FindRect (const char *name, BRect *rect) const
	Find a rectangle at the label name.
status_t	FindRef (const char *name, int32 index, entry_ref *ref) const
	Find a reference to a file at the label name at an index.
status_t	FindRef (const char *name, entry_ref *ref) const
	Find a reference to a file at the label name.
status_t	FindString (const char *name, int32 index, BString *string) const
	Find a string at the label name at an index.
status_t	FindString (const char *name, BString *string) const
	Find a string at the label name.
status_t	FindString (const char *name, int32 index, const char **string) const
	Find a string at the label name at an index.
status_t	FindString (const char *name, const char **string) const
	Find a string at the label name.
Flattening methods
Because of historical reasons and for binary compatibility, this class provides a flattening API without inheriting the BFlattenable class. The API is more or less the same, but you are inconvenienced when you want to use messages in methods that handle BFlattenable objects.
status_t	Flatten (BDataIO *stream, ssize_t *size=NULL) const
	Flatten the message to a stream.
status_t	Flatten (char *buffer, ssize_t size) const
	Flatten the message to a buffer.
ssize_t	FlattenedSize () const
	Return the size in bytes required when you want to flatten this message to a stream of bytes.
status_t	Unflatten (BDataIO *stream)
	Unflatten a message from a stream and put it into the current object.
status_t	Unflatten (const char *flatBuffer)
	Unflatten a message from a buffer and put it into the current object.
Removing Data
status_t	MakeEmpty ()
	Clear all data and metadata in this message.
status_t	RemoveData (const char *name, int32 index=0)
	Remove data associated with name at a specified index.
status_t	RemoveName (const char *name)
	Remove all data associated with a name.
Replacing Data
Look at ReplaceData() for a general introduction to replacing data.
status_t	ReplaceBool (const char *name, int32 index, bool aBoolean)
	Replace a boolean at the label name at a specified index.
status_t	ReplaceBool (const char *name, bool aBoolean)
	Replace a boolean at the label name.
status_t	ReplaceData (const char *name, type_code type, int32 index, const void *data, ssize_t numBytes)
	Replace the data at label name at a specified index.
status_t	ReplaceData (const char *name, type_code type, const void *data, ssize_t numBytes)
	Replace the data at label name.
status_t	ReplaceDouble (const char *name, int32 index, double aDouble)
	Replace a double at the label name at a specified index.
status_t	ReplaceDouble (const char *name, double aDouble)
	Replace a double at the label name.
status_t	ReplaceFlat (const char *name, int32 index, BFlattenable *object)
	Replace a flattened object at the label name at a specified index.
status_t	ReplaceFlat (const char *name, BFlattenable *object)
	Replace a flattened object at the label name.
status_t	ReplaceFloat (const char *name, int32 index, float aFloat)
	Replace a float at the label name at a specified index.
status_t	ReplaceFloat (const char *name, float aFloat)
	Replace a float at the label name.
status_t	ReplaceInt16 (const char *name, int32 index, int16 value)
	Replace an integer at the label name at a specified index.
status_t	ReplaceInt16 (const char *name, int16 value)
	Replace an integer at the label name.
status_t	ReplaceInt32 (const char *name, int32 index, int32 value)
	Replace an integer at the label name at a specified index.
status_t	ReplaceInt32 (const char *name, int32 value)
	Replace an integer at the label name.
status_t	ReplaceInt64 (const char *name, int32 index, int64 value)
	Replace an integer at the label name at a specified index.
status_t	ReplaceInt64 (const char *name, int64 value)
	Replace an integer at the label name.
status_t	ReplaceInt8 (const char *name, int32 index, int8 value)
	Replace an integer at the label name at a specified index.
status_t	ReplaceInt8 (const char *name, int8 value)
	Replace an integer at the label name.
status_t	ReplaceMessage (const char *name, int32 index, const BMessage *message)
	Replace a message at the label name at a specified index.
status_t	ReplaceMessage (const char *name, const BMessage *message)
	Replace a message at the label name.
status_t	ReplaceMessenger (const char *name, int32 index, BMessenger messenger)
	Replace a messenger at the label name at a specified index.
status_t	ReplaceMessenger (const char *name, BMessenger messenger)
	Replace a messenger at the label name.
status_t	ReplacePoint (const char *name, int32 index, BPoint aPoint)
	Replace a point at the label name at a specified index.
status_t	ReplacePoint (const char *name, BPoint aPoint)
	Replace a point at the label name.
status_t	ReplacePointer (const char *name, int32 index, const void *pointer)
	Replace a pointer at the label name at a specified index.
status_t	ReplacePointer (const char *name, const void *pointer)
	Replace a pointer at the label name.
status_t	ReplaceRect (const char *name, int32 index, BRect aRect)
	Replace a rectangle at the label name at a specified index.
status_t	ReplaceRect (const char *name, BRect aRect)
	Replace a rectangle at the label name.
status_t	ReplaceRef (const char *name, int32 index, const entry_ref *ref)
	Replace a reference to a file at the label name at a specified index.
status_t	ReplaceRef (const char *name, const entry_ref *ref)
	Replace a reference to a file at the label name.
status_t	ReplaceString (const char *name, int32 index, const BString &aString)
	Replace a string at the label name at a specified index.
status_t	ReplaceString (const char *name, const BString &aString)
	Replace a string at the label name.
status_t	ReplaceString (const char *name, int32 index, const char *aString)
	Replace a string at the label name at a specified index.
status_t	ReplaceString (const char *name, const char *aString)
	Replace a string at the label name.
Replying
status_t	SendReply (BMessage *the_reply, BMessage *replyToReply, bigtime_t sendTimeout=B_INFINITE_TIMEOUT, bigtime_t replyTimeout=B_INFINITE_TIMEOUT)
	Synchronously send a reply to this message, and wait for a reply back.
status_t	SendReply (uint32 command, BMessage *replyToReply)
	Synchronously send a reply to this message, and wait for a reply back.
status_t	SendReply (BMessage *reply, BMessenger replyTo, bigtime_t timeout=B_INFINITE_TIMEOUT)
	Asynchronously send a reply to this message.
status_t	SendReply (BMessage *reply, BHandler *replyTo=NULL, bigtime_t timeout=B_INFINITE_TIMEOUT)
	Asynchronously send a reply to this message.
status_t	SendReply (uint32 command, BHandler *replyTo=NULL)
	Asynchronously send a reply to this message.
Public Attributes
uint32	what
	A 4-byte constant that determines the type of message.

---

Detailed Description

A container that can be send and received using the Haiku messaging subsystem.

This class is at the center of the web of messaging classes, in the sense that it defines the actual structure of the messages. Messages have two important elements: the what identifer, and the data members. The first can be directly manipulated, the latter can be manipulated through AddData(), FindData() and ReplaceData() and their deratives. Neither of these elements are mandatory.

The second important role of BMessage is that it stores meta data: who sent the message and with what intention? The methods of BMessage will disclose if the message was a reply (IsReply()), where it came from (IsSourceRemote()), whether a reply is expected (IsSourceWaiting()), and in case the message is a reply, what it's a reply to (Previous()).

Mostly, messages are used to pass information between the the objects in your application, but because messages are such flexible data containers, they are also often used for other data storage purposes. Many applications store their settings as messages. Because messages can be flattened to data streams (such as files), they provide an easy but powerful tool for data storage.

All methods can be classified in these areas:

• Adding, Finding, Replacing and Removing Data.
• Statistics and Miscelanous information.
• Delivery information.
• Utilities to reply to messages.

To see how messages fit in with the greater picture, have a look at the Messaging Introduction.

---

Constructor & Destructor Documentation

BMessage::BMessage

(

)

Construct an empty message, without any data members and with a what constant set to zero (0).

See also:

BMessage(uint32 what)

BMessage(const BMessage &other)

BMessage::BMessage

(

uint32

what

)

Construct an empty message with the what member set tot the specified value.

See also:

BMessage::BMessage()

BMessage::BMessage(const BMessage &other)

BMessage::BMessage

(

const BMessage &

other

)

Construct a new message that is a copy of another message.

The what member and the data values are copied. The metadata, such as whether or not the message is a drop message or reply information, is not copied. So if the original message is a reply to a previous message, which will make IsReply() return true, calling the same method on a copy of the message will return false.

Remarks:

BeOS R5 did keep the metadata of the message. Haiku deviates from this behaviour. Please use the Haiku implementation of message copying as the default behavior. This will keep your applications backwards compatible.

See also:

BMessage::BMessage()

BMessage(uint32 what)

BMessage::~BMessage

(

)

[virtual]

Free the data members associated with the message.

If there still is a sender waiting for a reply, the B_NO_REPLY message will be sent to inform them that there won't be a reply.

---

Member Function Documentation

status_t BMessage::AddBool	(	const char *	name,
		bool	aBoolean
	)

Convenience method to add a bool to the label name.

This method calls AddData() with the B_BOOL_TYPE type.

Parameters:

	name	The label to associate the data with.
	aBoolean	The value to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindBool()

ReplaceBool()

status_t BMessage::AddData	(	const char *	name,
		type_code	type,
		const void *	data,
		ssize_t	numBytes,
		bool	isFixedSize = true,
		int32	count = 1
	)

Add data of a certain type to the message.

The amount of numBytes is copied into the message. The data is stored at the label specified in name. You are responsible for specifying the correct type. The Haiku API already specifies many constants, such as B_FLOAT_TYPE or B_RECT_TYPE. See TypeConstants.h for more information on the system-wide defined types.

If the field with the name already exists, the data is added in an array-like form. If you are adding a certain name for the first time, you are able to specify some properties of this array. You can fix the size of each data entry, and you can also instruct BMessage to allocate a count of items. The latter does not mean that the number of items is fixed; the array will grow nonetheless. Also, note that every name can only be associated with one type of data. If consecutive method calls specify a different type than the initial, these calls will fail.

There is no limit to the number of labels, or the amount of data, but note that searching of data members is linear, as well as that some messages will be copied whilst being passed around, so if the amount of data you need to pass is too big, find another way to pass it.

Parameters:

	name	The label to which this data needs to be associated. If the name already exists, the new data will be added in an array-like style.
	type	The type of data. If you are adding data to the same name, make sure it is the same type.
	data	The data buffer to copy the bytes from.
	numBytes	The number of bytes to be copied. If this is the first call to this method for this type of data, and you set isFixedSize to true, this will specify the size of all consecutive calls to this method.
	isFixedSize	If this is the first call to this method with this name, you can specify the whether or not all items in this array should have the same fixed size.
	count	If this is the first call to this method with this name, you can instruct this message to allocate a number of items in advance. This does not limit the amount of items though. The array will grow if needed.

Return values:

	B_OK	The data is succesfully added.
	B_BAD_VALUE	The numBytes is less than, or equal to zero (0), or the size of this item is larger than the name allows, since it has been specified to have a fixed size.
	B_ERROR	There was an error whilst creating the label with your name.
	B_BAD_TYPE	The type you specified is different than the one already associated with name.

status_t BMessage::AddDouble	(	const char *	name,
		double	aDouble
	)

Convenience method to add a double to the label name.

This method calls AddData() with the B_DOUBLE_TYPE type.

Parameters:

	name	The label to associate the data with.
	aDouble	The value to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindDouble()

ReplaceDouble()

status_t BMessage::AddFlat	(	const char *	name,
		BFlattenable *	object,
		int32	count = 1
	)

Convenience method to add a flattenable to the label name.

This method uses BFlattenable::TypeCode() to determine the type. It also uses BFlattenable::IsFixedSize() to determine whether or not the size of the object is supposedly always the same. You can specify a count, to pre-allocate more entries if you are going to add more than one of this type.

Parameters:

	name	The label to associate the data with.
	object	The object to flatten into the message.
	count	The number of items to pre-allocate associated with this name.

See also:

AddData() for a more detailed overview of the inner workings.

FindFlat()

ReplaceFlat()

status_t BMessage::AddFloat	(	const char *	name,
		float	aFloat
	)

Convenience method to add a float to the label name.

This method calls AddData() with the B_FLOAT_TYPE type.

Parameters:

	name	The label to associate the data with.
	aFloat	The value to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindFloat()

ReplaceFloat()

status_t BMessage::AddInt16	(	const char *	name,
		int16	value
	)

Convenience method to add an int16 to the label name.

This method calls AddData() with the B_INT16_TYPE type.

Parameters:

	name	The label to associate the data with.
	value	The value to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindInt16()

ReplaceInt16()

status_t BMessage::AddInt32	(	const char *	name,
		int32	value
	)

Convenience method to add an int32 to the label name.

This method calls AddData() with the B_INT32_TYPE type.

Parameters:

	name	The label to associate the data with.
	value	The value to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindInt32()

ReplaceInt32()

status_t BMessage::AddInt64	(	const char *	name,
		int64	value
	)

Convenience method to add an int64 to the label name.

This method calls AddData() with the B_INT64_TYPE type.

Parameters:

	name	The label to associate the data with.
	value	The value to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindInt64()

ReplaceInt64()

status_t BMessage::AddInt8	(	const char *	name,
		int8	value
	)

Convenience method to add an int8 to the label name.

This method calls AddData() with the B_INT8_TYPE type.

Parameters:

	name	The label to associate the data with.
	value	The value to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindInt8()

ReplaceInt8()

status_t BMessage::AddMessage	(	const char *	name,
		const BMessage *	message
	)

Convenience method to add a message to the label name.

This method calls AddData() with the B_MESSAGE_TYPE type.

Parameters:

	name	The label to associate the data with.
	message	The message to store in this message.

See also:

AddData() for a more detailed overview of the inner workings.

FindMessage()

ReplaceMessage()

status_t BMessage::AddMessenger	(	const char *	name,
		BMessenger	messenger
	)

Convenience method to add a messenger to the label name.

This method calls AddData() with the B_MESSENGER_TYPE type.

Parameters:

	name	The label to associate the data with.
	messenger	The messenger to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindMessenger()

ReplaceMessenger()

status_t BMessage::AddPoint	(	const char *	name,
		BPoint	aPoint
	)

Convenience method to add a BPoint to the label name.

This method calls AddData() with the B_POINT_TYPE type.

Parameters:

	name	The label to associate the data with.
	aPoint	The point to store in the message.

See also:

AddData() for a more detailed overview of the inner workings.

FindPoint()

ReplacePoint()

status_t BMessage::AddPointer	(	const char *	name,
		const void *	aPointer