A BMessage is a bundle of structured information. Every BMessage contains a command constant and some number of data fields.

Neither the command constant nor the data fields are mandatory. You can create a BMessage that has data but no command, or that only has a command. However, creating a BMessage that has neither is pointless.

Preparatory Reading

BMessages are used throughout the kits to send data (or notifications) to another threadpossibly in another application. To understand how BMessages fit into the messaging system, see "Messaging".

The BMessage class also contributes a number of functions that help define the scripting system. See "Scripting" for an introduction to this system.

BMessages are also used by a number of classes (BClipboard, BArchivable, and others) for their ability to store data.

Types of Functions

The BMessage class defines five types of functions:

Data field functions.

These functions either set or retrieve the value of a data field. See AddData(), FindData(), ReplaceData(), and RemoveName().

Info functions.

These functions retrieve information about the state and contents of the BMessage. See IsSystem() and GetInfo().

Messaging functions.

These functions are part of the messaging system. A smaller set of functions reports on the status of a received message. For example, IsSourceWaiting() tells whether the message sender is waiting for a reply, WasDropped() says whether it was dragged and dropped, and DropPoint() says where it was dropped.

Scripting functions.

Functions such as AddSpecifier() and PopSpecifier().

Flattening functions.

The data in a BMessage can be flattened into an untyped stream of bytes. See Flatten().

BMessage Ownership

The documentation for the functions that accept or pass back a BMessage object should tell you who's responsible for deleting the object. Most functions that accept a BMessage argument copy the object, leaving the caller with the responsibility for deleting the argument. The exceptions i.e. BMessage-accepting functions that take over ownership of the object are listed below:

Functions that return a BMessage to you usually don't give up ownership; in general, you don't delete the BMessages that are passed to you. The exceptions, functions that expect the caller to take over ownership of a passed-back BMessage,are listed below:

Creative Commons License
Legal Notice
This work is licensed under a Creative Commons Attribution-Non commercial-No Derivative Works 3.0 License.