Public Member Functions | Public Attributes | List of all members
BMessage Class Reference

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

Inherited by BMailAddOnSettings.

Public Member Functions

 BMessage ()
 Construct an empty message, without any data members and with a what constant set to 0. More...
 
 BMessage (uint32 what)
 Construct an empty message with the what member set to the specified value. More...
 
 BMessage (const BMessage &other)
 Construct a new message that is a copy of another message. More...
 
virtual ~BMessage ()
 Free the data members associated with the message. More...
 
Operators

The new and delete operators are deprecated and are only provided for backwards compatibility.

BMessageoperator= (const BMessage &other)
 Copy one message into another. More...
 
void * operator new (size_t size)
 Allocates size bytes of memory for a BMessage. More...
 
void * operator new (size_t, void *pointer)
 Allocates size bytes of memory for a BMessage. More...
 
void operator delete (void *pointer, size_t size)
 Frees memory allocated by new. More...
 
Statistics and Miscellaneous Information
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. More...
 
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. More...
 
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. More...
 
int32 CountNames (type_code type) const
 Count the number of names of a certain type. More...
 
bool IsEmpty () const
 Check if the message has data members. More...
 
bool IsSystem () const
 Check if the message is a system message. More...
 
bool IsReply () const
 Check if the message is a reply to a (previous) message. More...
 
void PrintToStream () const
 Print the message to the standard output. More...
 
status_t Rename (const char *oldEntry, const char *newEntry)
 Rename a data label. More...
 
Delivery Info
bool WasDelivered () const
 Check if this message was delivered through the delivery methods. More...
 
bool IsSourceWaiting () const
 Check if the sender expects a reply. More...
 
bool IsSourceRemote () const
 Check if the message is sent by another application. More...
 
BMessenger ReturnAddress () const
 Get a messenger that points to the sender of the message. More...
 
const BMessagePrevious () const
 Get the message to which this message is a reply. More...
 
bool WasDropped () const
 Check if the message was delivered through 'drag and drop'. More...
 
BPoint DropPoint (BPoint *offset=NULL) const
 Get the coordinates of the drop point of the message. More...
 
Replying
status_t SendReply (uint32 command, BHandler *replyTo=NULL)
 Asynchronously send a reply to this message. More...
 
status_t SendReply (BMessage *reply, BHandler *replyTo=NULL, bigtime_t timeout=B_INFINITE_TIMEOUT)
 Asynchronously send a reply to this message. More...
 
status_t SendReply (BMessage *reply, BMessenger replyTo, bigtime_t timeout=B_INFINITE_TIMEOUT)
 Asynchronously send a reply to this message. More...
 
status_t SendReply (uint32 command, BMessage *replyToReply)
 Synchronously send a reply to this message, and wait for a reply back. More...
 
status_t SendReply (BMessage *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. More...
 
Flattening

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.

ssize_t FlattenedSize () const
 Return the size in bytes required when you want to flatten this message to a stream of bytes. More...
 
status_t Flatten (char *buffer, ssize_t size) const
 Flatten the message to a buffer. More...
 
status_t Flatten (BDataIO *stream, ssize_t *size=NULL) const
 Flatten the message to a stream. More...
 
status_t Unflatten (const char *flatBuffer)
 Unflatten a message from a buffer and put it into the current object. More...
 
status_t Unflatten (BDataIO *stream)
 Unflatten a message from a stream and put it into the current object. More...
 
Specifiers (Scripting)
status_t AddSpecifier (const char *property)
 Undocumented. More...
 
status_t AddSpecifier (const char *property, int32 index)
 Undocumented. More...
 
status_t AddSpecifier (const char *property, int32 index, int32 range)
 Undocumented. More...
 
status_t AddSpecifier (const char *property, const char *name)
 Undocumented. More...
 
status_t AddSpecifier (const BMessage *specifier)
 Undocumented. More...
 
status_t SetCurrentSpecifier (int32 index)
 Undocumented. More...
 
status_t GetCurrentSpecifier (int32 *index, BMessage *specifier=NULL, int32 *what=NULL, const char **property=NULL) const
 Undocumented. More...
 
bool HasSpecifiers () const
 Undocumented. More...
 
status_t PopSpecifier ()
 Undocumented. More...
 
Adding Data
status_t AddRect (const char *name, BRect rect)
 Convenience method to add a BRect to the label name. More...
 
status_t AddPoint (const char *name, BPoint point)
 Convenience method to add a BPoint to the label name. More...
 
status_t AddString (const char *name, const char *string)
 Convenience method to add a C-string to the label name. More...
 
status_t AddString (const char *name, const BString &string)
 Convenience method to add a BString to the label name. More...
 
status_t AddInt8 (const char *name, int8 value)
 Convenience method to add an int8 to the label name. More...
 
status_t AddInt16 (const char *name, int16 value)
 Convenience method to add an int16 to the label name. More...
 
status_t AddInt32 (const char *name, int32 value)
 Convenience method to add an int32 to the label name. More...
 
status_t AddInt64 (const char *name, int64 value)
 Convenience method to add an int64 to the label name. More...
 
status_t AddBool (const char *name, bool value)
 Convenience method to add a bool to the label name. More...
 
status_t AddFloat (const char *name, float value)
 Convenience method to add a float to the label name. More...
 
status_t AddDouble (const char *name, double value)
 Convenience method to add a double to the label name. More...
 
status_t AddColor (const char *name, rgb_color value)
 Convenience method to add a rgb_color to the label name. More...
 
status_t AddPointer (const char *name, const void *pointer)
 Convenience method to add a pointer to the label name. More...
 
status_t AddMessenger (const char *name, BMessenger messenger)
 Convenience method to add a messenger to the label name. More...
 
status_t AddRef (const char *name, const entry_ref *ref)
 Convenience method to add an entry_ref to the label name. More...
 
status_t AddMessage (const char *name, const BMessage *message)
 Convenience method to add a message to the label name. More...
 
status_t AddFlat (const char *name, BFlattenable *object, int32 count=1)
 Convenience method to add a flattenable to the label name. More...
 
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. More...
 
Removing Data
status_t RemoveData (const char *name, int32 index=0)
 Remove data associated with name at a specified index. More...
 
status_t RemoveName (const char *name)
 Remove all data associated with a name. More...
 
status_t MakeEmpty ()
 Clear all data and metadata in this message. More...
 
Finding Data

Look at FindData() for a general introduction to finding data.

status_t FindRect (const char *name, BRect *rect) const
 Find a rectangle at the label name. More...
 
status_t FindRect (const char *name, int32 index, BRect *rect) const
 Find a rectangle at the label name at an index. More...
 
status_t FindPoint (const char *name, BPoint *point) const
 Find a point at the label name. More...
 
status_t FindPoint (const char *name, int32 index, BPoint *point) const
 Find a point at the label name at an index. More...
 
status_t FindString (const char *name, const char **string) const
 Find a string at the label name. More...
 
status_t FindString (const char *name, int32 index, const char **string) const
 Find a string at the label name at an index. More...
 
status_t FindString (const char *name, BString *string) const
 Find a string at the label name. More...
 
status_t FindString (const char *name, int32 index, BString *string) const
 Find a string at the label name at an index. More...
 
status_t FindInt8 (const char *name, int8 *value) const
 Find an integer at the label name. More...
 
status_t FindInt8 (const char *name, int32 index, int8 *value) const
 Find an integer at the label name at an index. More...
 
status_t FindInt16 (const char *name, int16 *value) const
 Find an integer at the label name. More...
 
status_t FindInt16 (const char *name, int32 index, int16 *value) const
 Find an integer at the label name at an index. More...
 
status_t FindInt32 (const char *name, int32 *value) const
 Find an integer at the label name. More...
 
status_t FindInt32 (const char *name, int32 index, int32 *value) const
 Find an integer at the label name at an index. More...
 
status_t FindInt64 (const char *name, int64 *value) const
 Find an integer at the label name. More...
 
status_t FindInt64 (const char *name, int32 index, int64 *value) const
 Find an integer at the label name at an index. More...
 
status_t FindBool (const char *name, bool *value) const
 Find a boolean at the label name. More...
 
status_t FindBool (const char *name, int32 index, bool *value) const
 Find a boolean at the label name at an index. More...
 
status_t FindFloat (const char *name, float *value) const
 Find a float at the label name. More...
 
status_t FindFloat (const char *name, int32 index, float *value) const
 Find a float at the label name at an index. More...
 
status_t FindDouble (const char *name, double *value) const
 Find a double at the label name. More...
 
status_t FindDouble (const char *name, int32 index, double *value) const
 Find a double at the label name at an index. More...
 
status_t FindColor (const char *name, rgb_color *value) const
 Find a color with the label name. More...
 
status_t FindColor (const char *name, int32 index, rgb_color *value) const
 Find a color at the label name at an index. More...
 
status_t FindPointer (const char *name, void **pointer) const
 Find a pointer at the label name. More...
 
status_t FindPointer (const char *name, int32 index, void **pointer) const
 Find a pointer at the label name at an index. More...
 
status_t FindMessenger (const char *name, BMessenger *messenger) const
 Find a messenger at the label name. More...
 
status_t FindMessenger (const char *name, int32 index, BMessenger *messenger) const
 Find a messenger at the label name at an index. More...
 
status_t FindRef (const char *name, entry_ref *ref) const
 Find a reference to a file at the label name. More...
 
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. More...
 
status_t FindMessage (const char *name, BMessage *message) const
 Find a message at the label name. More...
 
status_t FindMessage (const char *name, int32 index, BMessage *message) const
 Find a message at the label name at an index. More...
 
status_t FindFlat (const char *name, BFlattenable *object) const
 Find a flattened object at the label name. More...
 
status_t FindFlat (const char *name, int32 index, BFlattenable *object) const
 Find a flattened object at the label name at an index. More...
 
status_t FindData (const char *name, type_code type, const void **data, ssize_t *numBytes) const
 Find data that is stored in this message. More...
 
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. More...
 
Replacing Data

Look at ReplaceData() for a general introduction to replacing data.

status_t ReplaceRect (const char *name, BRect rect)
 Replace a rectangle at the label name. More...
 
status_t ReplaceRect (const char *name, int32 index, BRect rect)
 Replace a rectangle at the label name at a specified index. More...
 
status_t ReplacePoint (const char *name, BPoint aPoint)
 Replace a point at the label name. More...
 
status_t ReplacePoint (const char *name, int32 index, BPoint aPoint)
 Replace a point at the label name at a specified index. More...
 
status_t ReplaceString (const char *name, const char *string)
 Replace a string at the label name. More...
 
status_t ReplaceString (const char *name, int32 index, const char *string)
 Replace a string at the label name at a specified index. More...
 
status_t ReplaceString (const char *name, const BString &string)
 Replace a string at the label name. More...
 
status_t ReplaceString (const char *name, int32 index, const BString &string)
 Replace a string at the label name at a specified index. More...
 
status_t ReplaceInt8 (const char *name, int8 value)
 Replace an integer at the label name. More...
 
status_t ReplaceInt8 (const char *name, int32 index, int8 value)
 Replace an integer at the label name at a specified index. More...
 
status_t ReplaceInt16 (const char *name, int16 value)
 Replace an integer at the label name. More...
 
status_t ReplaceInt16 (const char *name, int32 index, int16 value)
 Replace an integer at the label name at a specified index. More...
 
status_t ReplaceInt32 (const char *name, int32 value)
 Replace an integer at the label name. More...
 
status_t ReplaceInt32 (const char *name, int32 index, int32 value)
 Replace an integer at the label name at a specified index. More...
 
status_t ReplaceInt64 (const char *name, int64 value)
 Replace an integer at the label name. More...
 
status_t ReplaceInt64 (const char *name, int32 index, int64 value)
 Replace an integer at the label name at a specified index. More...
 
status_t ReplaceBool (const char *name, bool aBoolean)
 Replace a boolean at the label name. More...
 
status_t ReplaceBool (const char *name, int32 index, bool value)
 Replace a boolean at the label name at a specified index. More...
 
status_t ReplaceFloat (const char *name, float value)
 Replace a float at the label name. More...
 
status_t ReplaceFloat (const char *name, int32 index, float value)
 Replace a float at the label name at a specified index. More...
 
status_t ReplaceDouble (const char *name, double value)
 Replace a double at the label name. More...
 
status_t ReplaceDouble (const char *name, int32 index, double value)
 Replace a double at the label name at a specified index. More...
 
status_t ReplaceColor (const char *name, rgb_color value)
 Replace a color at the label name. More...
 
status_t ReplaceColor (const char *name, int32 index, rgb_color value)
 Replace a rgb_color at the label name at a specified index. More...
 
status_t ReplacePointer (const char *name, const void *pointer)
 Replace a pointer at the label name. More...
 
status_t ReplacePointer (const char *name, int32 index, const void *pointer)
 Replace a pointer at the label name at a specified index. More...
 
status_t ReplaceMessenger (const char *name, BMessenger messenger)
 Replace a messenger at the label name. More...
 
status_t ReplaceMessenger (const char *name, int32 index, BMessenger messenger)
 Replace a messenger at the label name at a specified index. More...
 
status_t ReplaceRef (const char *name, const entry_ref *ref)
 Replace a reference to a file at the label name. More...
 
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. More...
 
status_t ReplaceMessage (const char *name, const BMessage *message)
 Replace a message at the label name. More...
 
status_t ReplaceMessage (const char *name, int32 index, const BMessage *message)
 Replace a message at the label name at a specified index. More...
 
status_t ReplaceFlat (const char *name, BFlattenable *object)
 Replace a flattened object at the label name. More...
 
status_t ReplaceFlat (const char *name, int32 index, BFlattenable *object)
 Replace a flattened object at the label name at a specified index. More...
 
status_t ReplaceData (const char *name, type_code type, const void *data, ssize_t numBytes)
 Replace the data at label name. More...
 
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. More...
 
Deprecated Methods

These methods are likely to disappear as they have been replaced by safer and more powerful methods but are implemented for the purpose of binary compatibility.

bool HasRect (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasPoint (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasString (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasInt8 (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasInt16 (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasInt32 (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasInt64 (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasBool (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasFloat (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasDouble (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasPointer (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasMessenger (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasRef (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasMessage (const char *name, int32 n=0) const
 Deprecated. More...
 
bool HasFlat (const char *name, const BFlattenable *object) const
 Deprecated. More...
 
bool HasFlat (const char *name, int32 n, const BFlattenable *object) const
 Deprecated. More...
 
bool HasData (const char *name, type_code, int32 n=0) const
 Deprecated. More...
 
BRect FindRect (const char *name, int32 n=0) const
 Deprecated. More...
 
BPoint FindPoint (const char *name, int32 n=0) const
 Deprecated. More...
 
const char * FindString (const char *name, int32 n=0) const
 Deprecated. More...
 
int8 FindInt8 (const char *name, int32 n=0) const
 Deprecated. More...
 
int16 FindInt16 (const char *name, int32 n=0) const
 Deprecated. More...
 
int32 FindInt32 (const char *name, int32 n=0) const
 Deprecated. More...
 
int64 FindInt64 (const char *name, int32 n=0) const
 Deprecated. More...
 
bool FindBool (const char *name, int32 n=0) const
 Deprecated. More...
 
float FindFloat (const char *name, int32 n=0) const
 Deprecated. More...
 
double FindDouble (const char *name, int32 n=0) const
 Deprecated. More...
 
Finding Data Convenience Methods

These methods may be used as alternatives to the Find data methods above which allow you to specify a default value to use if the value you are looking for is not found and return the result instead of filling out an out parameter and status code. If you are not interested in the status code these methods allow for some code simplification.

For example, instead of writing:

bool enabled;
if (FindBool("enabled", &enabled) != B_OK)
enabled = false;

you can write the following:

bool enabled = GetBool("enabled", false);

reducing the example to a single line.

bool GetBool (const char *name, bool defaultValue=false) const
 Return the boolean value from message with name, or defaultValue if not found. More...
 
bool GetBool (const char *name, int32 index, bool defaultValue) const
 Return the boolean value from message with name and index, or defaultValue if not found. More...
 
int8 GetInt8 (const char *name, int8 defaultValue) const
 Return the int8 value from message with name, or defaultValue if not found. More...
 
int8 GetInt8 (const char *name, int32 index, int8 defaultValue) const
 Return the int8 value from message with name and index, or defaultValue if not found. More...
 
uint8 GetUInt8 (const char *name, uint8 defaultValue) const
 Return the uint8 value from message with name, or defaultValue if not found. More...
 
uint8 GetUInt8 (const char *name, int32 index, uint8 defaultValue) const
 Return the uint8 message from message with name and index, or defaultValue if not found. More...
 
int16 GetInt16 (const char *name, int16 defaultValue) const
 Return the int16 value from message with name, or defaultValue if not found. More...
 
int16 GetInt16 (const char *name, int32 index, int16 defaultValue) const
 Return the int16 value from message with name and index, or defaultValue if not found. More...
 
uint16 GetUInt16 (const char *name, uint16 defaultValue) const
 Return the uint16 value from message with name, or defaultValue if not found. More...
 
uint16 GetUInt16 (const char *name, int32 index, uint16 defaultValue) const
 Return the uint16 value from message with name and index, or defaultValue if not found. More...
 
int32 GetInt32 (const char *name, int32 defaultValue) const
 Return the int32 value from message with name, or defaultValue if not found. More...
 
int32 GetInt32 (const char *name, int32 index, int32 defaultValue) const
 Return the int32 value from message with name and index, or defaultValue if not found. More...
 
uint32 GetUInt32 (const char *name, uint32 defaultValue) const
 Return the uint32 value from message with name, or defaultValue if not found. More...
 
uint32 GetUInt32 (const char *name, int32 index, uint32 defaultValue) const
 Return the uint32 value from message with name and index, or defaultValue if not found. More...
 
int64 GetInt64 (const char *name, int64 defaultValue) const
 Return the int64 value from message with name, or defaultValue if not found. More...
 
int64 GetInt64 (const char *name, int32 index, int64 defaultValue) const
 Return the int64 value from message with name and index, or defaultValue if not found. More...
 
uint64 GetUInt64 (const char *name, uint64 defaultValue) const
 Return the uint64 value from message with name, or defaultValue if not found. More...
 
uint64 GetUInt64 (const char *name, int32 index, uint64 defaultValue) const
 Return the uint64 value from message with name and index, or defaultValue if not found. More...
 
float GetFloat (const char *name, float defaultValue) const
 Return the float value from message with name, or defaultValue if not found. More...
 
float GetFloat (const char *name, int32 index, float defaultValue) const
 Return the float value from message with name and index, or defaultValue if not found. More...
 
double GetDouble (const char *name, double defaultValue) const
 Return the double value from message with name, or defaultValue if not found. More...
 
double GetDouble (const char *name, int32 index, double defaultValue) const
 Return the double value from message with name and index, or defaultValue if not found. More...
 
rgb_color GetColor (const char *name, rgb_color defaultValue) const
 Return the rgb_color value from message with name, or defaultValue if not found. More...
 
rgb_color GetColor (const char *name, int32 index, rgb_color defaultValue) const
 Return the rgb_color value from message with name and index, or defaultValue if not found. More...
 
const char * GetString (const char *name, const char *defaultValue=NULL) const
 Return the string from message with name, or defaultValue if not found. More...
 
const char * GetString (const char *name, int32 index, const char *defaultValue) const
 Return the string from message with name and index, or defaultValue if not found. More...
 
BAlignment GetAlignment (const char *name, int32 index, const BAlignment &defaultValue) const
 Return the BAlignment object from message with name and index, or defaultValue if not found. More...
 
BAlignment GetAlignment (const char *name, const BAlignment &defaultValue) const
 Return the BAlignment object from message with name, or defaultValue if not found. More...
 
BRect GetRect (const char *name, int32 index, const BRect &defaultValue) const
 Return the BRect object from message with name and index, or defaultValue if not found. More...
 
BRect GetRect (const char *name, const BRect &defaultValue) const
 Return the BRect object from message with name, or defaultValue if not found. More...
 
BPoint GetPoint (const char *name, int32 index, const BPoint &defaultValue) const
 Return the BPoint object from message with name and index, or defaultValue if not found. More...
 
BPoint GetPoint (const char *name, const BPoint &defaultValue) const
 Return the BPoint object from message with name, or defaultValue if not found. More...
 
BSize GetSize (const char *name, int32 index, const BSize &defaultValue) const
 Return the BSize object from message with name and index, or defaultValue if not found. More...
 
BSize GetSize (const char *name, const BSize &defaultValue) const
 Return the BSize object from message with name, or defaultValue if not found. More...
 

Public Attributes

uint32 what
 A 4-byte constant that determines the type of message. More...
 

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 identifier, and the data members. The first can be directly manipulated, the latter can be manipulated through AddData(), FindData() and ReplaceData() and their derivatives. 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:

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

Since
BeOS R3

Constructor & Destructor Documentation

◆ BMessage() [1/3]

BMessage::BMessage ( )

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

See also
BMessage(uint32 what)
BMessage(const BMessage& other)
Since
BeOS R3

◆ BMessage() [2/3]

BMessage::BMessage ( uint32  what)

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

See also
BMessage::BMessage()
BMessage::BMessage(const BMessage& other)
Since
BeOS R3

◆ BMessage() [3/3]

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. If the original message is a reply to a previous message this will make IsReply() return true, while calling the same method on a copy of the message will return false.

Remarks
BeOS kept the metadata of the message while Haiku deviates from this behavior. Use the Haiku implementation of message copying as the default behavior to keep your applications backwards compatible.
See also
BMessage::BMessage()
BMessage(uint32 what)
Since
BeOS R3

◆ ~BMessage()

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.

Since
BeOS R3

Member Function Documentation

◆ AddBool()

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
nameThe label to associate the data with.
aBooleanThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindBool()
GetBool()
ReplaceBool()
Since
BeOS R3

◆ AddColor()

status_t BMessage::AddColor ( const char *  name,
rgb_color  aColor 
)

Convenience method to add a rgb_color to the label name.

This method calls AddData() with the B_RGB_32_BIT_TYPE type.

Parameters
nameThe label to associate the data with.
aColorThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddColor() for a more detailed overview of the inner workings.
FindColor()
GetColor()
ReplaceColor()
Since
Haiku R1

◆ AddData()

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
nameThe 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.
typeThe type of data. If you are adding data to the same name, make sure it is the same type.
dataThe data buffer to copy the bytes from.
numBytesThe 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.
isFixedSizeIf 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.
countIf 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.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe data is succesfully added.
B_BAD_VALUEThe numBytes is less than, or equal to 0, or the size of this item is larger than the name allows, since it has been specified to have a fixed size.
B_ERRORThere was an error whilst creating the label with your name.
B_BAD_TYPEThe type you specified is different than the one already associated with name.
Since
BeOS R3

◆ AddDouble()

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
nameThe label to associate the data with.
aDoubleThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindDouble()
GetDouble()
ReplaceDouble()
Since
BeOS R3

◆ AddFlat()

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
nameThe label to associate the data with.
objectThe object to flatten into the message.
countThe number of items to pre-allocate associated with this name.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindFlat()
ReplaceFlat()
Since
BeOS R3

◆ AddFloat()

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
nameThe label to associate the data with.
aFloatThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindFloat()
GetFloat()
ReplaceFloat()
Since
BeOS R3

◆ AddInt16()

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
nameThe label to associate the data with.
valueThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindInt16()
GetInt16()
ReplaceInt16()
Since
BeOS R3

◆ AddInt32()

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
nameThe label to associate the data with.
valueThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindInt32()
GetInt32()
ReplaceInt32()
Since
BeOS R3

◆ AddInt64()

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
nameThe label to associate the data with.
valueThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindInt64()
GetInt64()
ReplaceInt64()
Since
BeOS R3

◆ AddInt8()

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
nameThe label to associate the data with.
valueThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindInt8()
GetInt8()
ReplaceInt8()
Since
BeOS R3

◆ AddMessage()

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
nameThe label to associate the data with.
messageThe message to store in this message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindMessage()
ReplaceMessage()
Since
BeOS R3

◆ AddMessenger()

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
nameThe label to associate the data with.
messengerThe messenger to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindMessenger()
ReplaceMessenger()
Since
BeOS R3

◆ AddPoint()

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
nameThe label to associate the data with.
aPointThe point to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindPoint()
GetPoint()
ReplacePoint()
Since
BeOS R3

◆ AddPointer()

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

Convenience method to add a pointer to the label name.

This method calls AddData() with the B_POINTER_TYPE type.

Warning
If you want to share objects between applications, remember that each application has its own address space, and that it therefore is useless to try to pass around objects by sending pointers in messages. You should think about copying the entire object in the message, or you should consider using shared memory.
Parameters
nameThe label to associate the data with.
aPointerThe value to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindPointer()
ReplacePointer()
Since
BeOS R3

◆ AddRect()

status_t BMessage::AddRect ( const char *  name,
BRect  aRect 
)

Convenience method to add a BRect to the label name.

This method calls AddData() with the B_RECT_TYPE type.

Parameters
nameThe label to associate the data with.
aRectThe rectangle to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindRect()
GetRect()
ReplaceRect()
Since
BeOS R3

◆ AddRef()

status_t BMessage::AddRef ( const char *  name,
const entry_ref ref 
)

Convenience method to add an entry_ref to the label name.

This method calls AddData() with the B_REF_TYPE type.

Parameters
nameThe label to associate the data with.
refThe reference to store in the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindRef()
ReplaceRef()
Since
BeOS R3

◆ AddSpecifier() [1/5]

status_t BMessage::AddSpecifier ( const char *  property)

Undocumented.

Since
BeOS R3

◆ AddSpecifier() [2/5]

status_t BMessage::AddSpecifier ( const char *  property,
int32  index 
)

Undocumented.

Since
BeOS R3

◆ AddSpecifier() [3/5]

status_t BMessage::AddSpecifier ( const char *  property,
int32  index,
int32  range 
)

Undocumented.

Since
BeOS R3

◆ AddSpecifier() [4/5]

status_t BMessage::AddSpecifier ( const char *  property,
const char *  name 
)

Undocumented.

Since
BeOS R3

◆ AddSpecifier() [5/5]

status_t BMessage::AddSpecifier ( const BMessage specifier)

Undocumented.

Since
BeOS R3

◆ AddString() [1/2]

status_t BMessage::AddString ( const char *  name,
const char *  aString 
)

Convenience method to add a C-string to the label name.

This method calls AddData() with the B_STRING_TYPE type.

Parameters
nameThe label to associate the data with.
aStringThe string to copy to the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindString()
GetString()
ReplaceString()
Since
BeOS R3

◆ AddString() [2/2]

status_t BMessage::AddString ( const char *  name,
const BString aString 
)

Convenience method to add a BString to the label name.

This method calls AddData() with the B_STRING_TYPE type.

Parameters
nameThe label to associate the data with.
aStringThe string to copy to the message.
Returns
A status code, B_OK on success or an error code.
See also
AddData() for a more detailed overview of the inner workings.
FindString()
GetString()
ReplaceString()
Since
BeOS R5

◆ CountNames()

int32 BMessage::CountNames ( type_code  type) const

Count the number of names of a certain type.

This method can be used to count the number of items of a certain type. It's practical use is limited to debugging purposes.

Parameters
typeThe type you want to find. If you pass B_ANY_TYPE, this method will return the total number of data items.
Returns
The number of data items in this message with the specified type, or 0 in case no items match the type.
Since
BeOS R3

◆ DropPoint()

BPoint BMessage::DropPoint ( BPoint offset = NULL) const

Get the coordinates of the drop point of the message.

If the message has been delivered because of drag and drop, which can be verified with the WasDropped() method, this method will return a BPoint to where exactly the drop off was made.

Because drop messages are delivered to the BWindow in which they were dropped, and BWindow is a subclass of BLooper, you can use BWindow to determine based on the location, how you should react to it.

If this message was not delivered through drag and drop, it will return a NULL pointer.

See also
WasDropped()
Since
BeOS R3

◆ FindBool() [1/3]

status_t BMessage::FindBool ( const char *  name,
bool *  value 
) const

Find a boolean at the label name.

This is an overloaded version of FindBool(const char*, int32, bool*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindBool() [2/3]

status_t BMessage::FindBool ( const char *  name,
int32  index,
bool *  value 
) const

Find a boolean at the label name at an index.

This method looks for the data with the B_BOOL_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindBool(const char*, bool*) const
Since
BeOS R3

◆ FindBool() [3/3]

bool BMessage::FindBool ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindColor() [1/2]

status_t BMessage::FindColor ( const char *  name,
rgb_color *  value 
) const

Find a color with the label name.

This is an overloaded version of FindColor(const char*, int32, rgb_color*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
Haiku R1

◆ FindColor() [2/2]

status_t BMessage::FindColor ( const char *  name,
int32  index,
rgb_color *  value 
) const

Find a color at the label name at an index.

This method looks for the data with the B_RGB_32_BIT_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindColor(const char*, rgb_color*) const
Since
BeOS R3

◆ FindData() [1/2]

status_t BMessage::FindData ( const char *  name,
type_code  type,
const void **  data,
ssize_t *  numBytes 
) const

Find data that is stored in this message.

This is an overloaded version of FindData(const char*, type_code, int32, const void**, ssize_t*) const where data is sought at index 0.

Since
BeOS R3

◆ FindData() [2/2]

status_t BMessage::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.

This method matches the label name with the type you are asking for, and it looks for the data that is stored at a certain index number. If all these things match, you will get a pointer to the internal buffer, and the method will put the size of the item in numBytes.

Note that only this method, and FindString(const char*, const char**), pass a pointer to the internal buffer. The other more specific methods, such as FindBool() and FindRect() copy the data into a buffer you specify. This means that the data retrieved with this method is valid until the message is deleted.

Parameters
nameThe label the data should be associated with.
typeThe type of data you want to retrieve. You can pass B_ANY_TYPE if you don't mind which type the data is.
indexThe index in the array of the data that you want to retrieve. Note that the array is zero-based.
[out]dataA pointer to a pointer where the data can point to.
[out]numBytesThe size of the data will be put in this parameter.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe name was found, matches the type, and the data at index has been put in data.
B_BAD_VALUEOne of the output arguments were NULL.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
status_t FindData(const char*, type_code, int32, const void**, ssize_t*) const
Since
BeOS R3

◆ FindDouble() [1/3]

status_t BMessage::FindDouble ( const char *  name,
double *  value 
) const

Find a double at the label name.

This is an overloaded version of FindDouble(const char*, int32, double*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindDouble() [2/3]

status_t BMessage::FindDouble ( const char *  name,
int32  index,
double *  value 
) const

Find a double at the label name at an index.

This method looks for the data with the B_DOUBLE_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindDouble(const char*, double*) const
Since
BeOS R3

◆ FindDouble() [3/3]

double BMessage::FindDouble ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindFlat() [1/2]

status_t BMessage::FindFlat ( const char *  name,
BFlattenable object 
) const

Find a flattened object at the label name.

This is an overloaded version of FindFlat(const char*, int32, BFlattenable*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
objectThe object in which the data should be unflattened.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindFlat() [2/2]

status_t BMessage::FindFlat ( const char *  name,
int32  index,
BFlattenable object 
) const

Find a flattened object at the label name at an index.

The type is determined by the type of the passed object. If that type is available at the specified label, then the Unflatten() method of that object will be called.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be unflattened.
objectThe object in which the data should be unflattened.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindFlat(const char*, BFlattenable*) const
Since
BeOS R3

◆ FindFloat() [1/3]

status_t BMessage::FindFloat ( const char *  name,
float *  value 
) const

Find a float at the label name.

This is an overloaded version of FindFloat(const char*, int32, float*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindFloat() [2/3]

status_t BMessage::FindFloat ( const char *  name,
int32  index,
float *  value 
) const

Find a float at the label name at an index.

This method looks for the data with the B_FLOAT_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindFloat(const char*, float*) const
Since
BeOS R3

◆ FindFloat() [3/3]

float BMessage::FindFloat ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindInt16() [1/3]

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

Find an integer at the label name.

This is an overloaded version of FindInt8(const char*, int32, int16*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindInt16() [2/3]

status_t BMessage::FindInt16 ( const char *  name,
int32  index,
int16 *  value 
) const

Find an integer at the label name at an index.

This method looks for the data with the B_INT16_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindInt16(const char*, int16*) const
Since
BeOS R3

◆ FindInt16() [3/3]

int16 BMessage::FindInt16 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindInt32() [1/3]

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

Find an integer at the label name.

This is an overloaded version of FindInt32(const char*, int32, int32*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindInt32() [2/3]

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

Find an integer at the label name at an index.

This method looks for the data with the B_INT32_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindInt32(const char*, int32*) const
Since
BeOS R3

◆ FindInt32() [3/3]

int32 BMessage::FindInt32 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindInt64() [1/3]

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

Find an integer at the label name.

This is an overloaded version of FindInt64(const char*, int32, int64*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindInt64() [2/3]

status_t BMessage::FindInt64 ( const char *  name,
int32  index,
int64 *  value 
) const

Find an integer at the label name at an index.

This method looks for the data with the B_INT64_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindInt64(const char*, int64*) const
Since
BeOS R3

◆ FindInt64() [3/3]

int64 BMessage::FindInt64 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindInt8() [1/3]

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

Find an integer at the label name.

This is an overloaded version of FindInt8(const char*, int32, int8*) const where the data is sought at index 0.

Since
BeOS R3

◆ FindInt8() [2/3]

status_t BMessage::FindInt8 ( const char *  name,
int32  index,
int8 *  value 
) const

Find an integer at the label name at an index.

This method looks for the data with the B_INT8_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
valueThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindInt8(const char*, int8*) const
Since
BeOS R3

◆ FindInt8() [3/3]

int8 BMessage::FindInt8 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindMessage() [1/2]

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

Find a message at the label name.

This is an overloaded version of FindMessage(const char*, int32, BMessage*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
messageThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindMessage() [2/2]

status_t BMessage::FindMessage ( const char *  name,
int32  index,
BMessage message 
) const

Find a message at the label name at an index.

This method looks for the data with the B_MESSAGE_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
messageThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindMessage(const char*, BMessage*) const
Since
BeOS R3

◆ FindMessenger() [1/2]

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

Find a messenger at the label name.

This is an overloaded version of FindMessenger(const char*, int32, BMessenger*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
messengerThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindMessenger() [2/2]

status_t BMessage::FindMessenger ( const char *  name,
int32  index,
BMessenger messenger 
) const

Find a messenger at the label name at an index.

This method looks for the data with the B_MESSENGER_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
messengerThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindMessenger(const char*, BMessenger*) const
Since
BeOS R3

◆ FindPoint() [1/3]

status_t BMessage::FindPoint ( const char *  name,
BPoint point 
) const

Find a point at the label name.

This is an overloaded version of FindPoint(const char*, int32, BPoint*) const where the data is sought at index 0.

Since
BeOS R3

◆ FindPoint() [2/3]

status_t BMessage::FindPoint ( const char *  name,
int32  index,
BPoint point 
) const

Find a point at the label name at an index.

This method looks for the data with the B_POINT_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
pointThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindPoint(const char*, BPoint*) const
Since
BeOS R3

◆ FindPoint() [3/3]

BPoint BMessage::FindPoint ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindPointer() [1/2]

status_t BMessage::FindPointer ( const char *  name,
void **  pointer 
) const

Find a pointer at the label name.

This is an overloaded version of FindPointer(const char*, int32, void*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
pointerThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindPointer() [2/2]

status_t BMessage::FindPointer ( const char *  name,
int32  index,
void **  pointer 
) const

Find a pointer at the label name at an index.

This method looks for the data with the B_POINTER_TYPE, and copies it into a provided buffer.

Warning
If you want to share objects between applications, remember that each application has its own address space, and that it therefore is useless to try to pass around objects by sending pointers in messages. You should think about copying the entire object in the message, or you should consider using shared memory.
Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
pointerThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindPointer(const char*, void*) const
Since
BeOS R3

◆ FindRect() [1/3]

status_t BMessage::FindRect ( const char *  name,
BRect rect 
) const

Find a rectangle at the label name.

This is an overloaded version of FindRect(const char*, int32, BRect*) const where the data is sought at index 0.

Since
BeOS R3

◆ FindRect() [2/3]

status_t BMessage::FindRect ( const char *  name,
int32  index,
BRect rect 
) const

Find a rectangle at the label name at an index.

This method looks for the data with the B_RECT_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
rectThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindRect(const char*, BRect*) const
Since
BeOS R3

◆ FindRect() [3/3]

BRect BMessage::FindRect ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ FindRef() [1/2]

status_t BMessage::FindRef ( const char *  name,
entry_ref ref 
) const

Find a reference to a file at the label name.

This is an overloaded version of FindRef(const char*, int32, entry_ref*) const where the data is sought at index 0.

Parameters
nameThe label to which the data is associated.
refThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ FindRef() [2/2]

status_t BMessage::FindRef ( const char *  name,
int32  index,
entry_ref ref 
) const

Find a reference to a file at the label name at an index.

This method looks for the data with the B_REF_TYPE, and copies it into a provided buffer.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
refThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindRef(const char*, entry_ref*) const
Since
BeOS R3

◆ FindString() [1/5]

status_t BMessage::FindString ( const char *  name,
const char **  string 
) const

Find a string at the label name.

This is an overloaded version of FindString(const char*, int32, const char**) const where the data is sought at index 0.

Since
BeOS R3

◆ FindString() [2/5]

status_t BMessage::FindString ( const char *  name,
int32  index,
const char **  string 
) const

Find a string at the label name at an index.

This method looks for the data with the B_STRING_TYPE, and returns a pointer to the internal buffer of the message. Note that this pointer is valid, until the message is deleted.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
stringThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindString(const char*, const char**) const
FindString(const char*, int32, BString*) const
Since
BeOS R3

◆ FindString() [3/5]

status_t BMessage::FindString ( const char *  name,
BString string 
) const

Find a string at the label name.

This is an overloaded version of FindString(const char*, int32, BString*) const where the data is sought at index 0.

Since
BeOS R5

◆ FindString() [4/5]

status_t BMessage::FindString ( const char *  name,
int32  index,
BString string 
) const

Find a string at the label name at an index.

This method looks for the data with the B_STRING_TYPE, and copies it into the string object.

Parameters
nameThe label to which the data is associated.
indexThe index from which the data should be copied.
stringThe object in which the data should be copied.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_BAD_INDEXThe index does not exist.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
FindString(const char*, BString*) const
FindString(const char*, int32, const char**) const
Since
BeOS R5

◆ FindString() [5/5]

const char * BMessage::FindString ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ Flatten() [1/2]

status_t BMessage::Flatten ( char *  buffer,
ssize_t  size 
) const

Flatten the message to a buffer.

Parameters
bufferThe buffer to write the data to.
sizeThe size of the buffer.
Returns
B_OK in case of success, or an error code in case something went awry.
Warning
Make sure the buffer is large enough to hold the message. This method does not double-check for you!
See also
FlattenedSize()
Flatten(BDataIO* stream, ssize_t* size) const
Since
BeOS R3

◆ Flatten() [2/2]

status_t BMessage::Flatten ( BDataIO stream,
ssize_t *  size = NULL 
) const

Flatten the message to a stream.

Parameters
[in]streamThe stream to flatten the message to.
[out]sizeThe method writes the number of bytes actually written to this argument.
Returns
B_OK in case of success, or an error code in case something went awry.
Warning
Make sure the subclass of the BDataIO interface either protects against buffer overwrites, or check if the number of bytes that is going to be written isn't larger than it can handle.
See also
FlattenedSize()
Flatten(char* buffer, ssize_t size) const
Since
BeOS R3

◆ FlattenedSize()

ssize_t BMessage::FlattenedSize ( ) const

Return the size in bytes required when you want to flatten this message to a stream of bytes.

Since
BeOS R3

◆ GetAlignment() [1/2]

BAlignment BMessage::GetAlignment ( const char *  name,
int32  index,
const BAlignment &  defaultValue 
) const

Return the BAlignment object from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetAlignment() [2/2]

BAlignment BMessage::GetAlignment ( const char *  name,
const BAlignment &  defaultValue 
) const

Return the BAlignment object from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetBool() [1/2]

bool BMessage::GetBool ( const char *  name,
bool  defaultValue = false 
) const

Return the boolean value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetBool() [2/2]

bool BMessage::GetBool ( const char *  name,
int32  index,
bool  defaultValue 
) const

Return the boolean value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetColor() [1/2]

rgb_color BMessage::GetColor ( const char *  name,
rgb_color  defaultValue 
) const

Return the rgb_color value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetColor() [2/2]

rgb_color BMessage::GetColor ( const char *  name,
int32  index,
rgb_color  defaultValue 
) const

Return the rgb_color value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetCurrentSpecifier()

status_t BMessage::GetCurrentSpecifier ( int32 *  index,
BMessage specifier = NULL,
int32 *  what = NULL,
const char **  property = NULL 
) const

Undocumented.

Since
BeOS R3

◆ GetDouble() [1/2]

double BMessage::GetDouble ( const char *  name,
double  defaultValue 
) const

Return the double value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetDouble() [2/2]

double BMessage::GetDouble ( const char *  name,
int32  index,
double  defaultValue 
) const

Return the double value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetFloat() [1/2]

float BMessage::GetFloat ( const char *  name,
float  defaultValue 
) const

Return the float value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetFloat() [2/2]

float BMessage::GetFloat ( const char *  name,
int32  index,
float  defaultValue 
) const

Return the float value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInfo() [1/3]

status_t BMessage::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.

Parameters
[in]typeRequestedIf you want to limit the search to only one type, pass that type code here. If you don't care which type the data has, you can pass B_ANY_TYPE.
[in]indexThe index of the data you want to investigate.
[out]nameFoundThe name of the item if it is found. Haiku will fill in a pointer to the internal name buffer in the message. This means that you should not manipulate this name. If you are not interested in the name, you can safely pass NULL.
[out]typeFoundThe type of the item at index. If you are not interested in the type (because you specifically asked for a type), you can safely pass NULL.
[out]countFoundThe number of items at index. If data items have the same name, they will be placed under the same index.
Returns
If the index is found, and matches the requested type, then the other parameters will be filled in. If this is not the case, the method will return with an error.
Return values
B_OKAn match was found. The values have been filled in.
B_BAD_INDEXThe index was out of range. None of the passed variables have been altered.
B_BAD_TYPEThe data field at index does not have the requested type.
Since
BeOS R3

◆ GetInfo() [2/3]

status_t BMessage::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.

Parameters
[in]nameThe name of the data member that you are looking for.
[out]typeFoundIn case of a match, the name of the data member will be put in this parameter. In case you are not interested, you can pass NULL.
[out]countFoundIn case of a match, the number of items at this label will be in this parameter. In case you are not interested, you can safely pass NULL.
Returns
If the message has data associated with the given name, the other parameters will contain information associated with the data, else, the method will return with an error.
Return values
B_OKA match was found. The other parameters have been filled in.
B_BAD_VALUEYou passed NULL as argument to name.
B_NAME_NOT_FOUNDThere is no data with the label name.
Since
BeOS R3

◆ GetInfo() [3/3]

status_t BMessage::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.

This method is the same as GetInfo(const char*, type_code*, int32*) const, with the difference that you can find out whether or not the size of the data associated with the name is fixed. You will get this value in the variable you passed as fixedSize parameter.

Since
BeOS R4

◆ GetInt16() [1/2]

int16 BMessage::GetInt16 ( const char *  name,
int16  defaultValue 
) const

Return the int16 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInt16() [2/2]

int16 BMessage::GetInt16 ( const char *  name,
int32  index,
int16  defaultValue 
) const

Return the int16 value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInt32() [1/2]

int32 BMessage::GetInt32 ( const char *  name,
int32  defaultValue 
) const

Return the int32 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInt32() [2/2]

int32 BMessage::GetInt32 ( const char *  name,
int32  index,
int32  defaultValue 
) const

Return the int32 value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInt64() [1/2]

int64 BMessage::GetInt64 ( const char *  name,
int64  defaultValue 
) const

Return the int64 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInt64() [2/2]

int64 BMessage::GetInt64 ( const char *  name,
int32  index,
int64  defaultValue 
) const

Return the int64 value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInt8() [1/2]

int8 BMessage::GetInt8 ( const char *  name,
int8  defaultValue 
) const

Return the int8 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetInt8() [2/2]

int8 BMessage::GetInt8 ( const char *  name,
int32  index,
int8  defaultValue 
) const

Return the int8 value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetPoint() [1/2]

BPoint BMessage::GetPoint ( const char *  name,
int32  index,
const BPoint defaultValue 
) const

Return the BPoint object from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetPoint() [2/2]

BPoint BMessage::GetPoint ( const char *  name,
const BPoint defaultValue 
) const

Return the BPoint object from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetRect() [1/2]

BRect BMessage::GetRect ( const char *  name,
int32  index,
const BRect defaultValue 
) const

Return the BRect object from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetRect() [2/2]

BRect BMessage::GetRect ( const char *  name,
const BRect defaultValue 
) const

Return the BRect object from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetSize() [1/2]

BSize BMessage::GetSize ( const char *  name,
int32  index,
const BSize defaultValue 
) const

Return the BSize object from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetSize() [2/2]

BSize BMessage::GetSize ( const char *  name,
const BSize defaultValue 
) const

Return the BSize object from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetString() [1/2]

const char * BMessage::GetString ( const char *  name,
const char *  defaultValue = NULL 
) const

Return the string from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetString() [2/2]

const char * BMessage::GetString ( const char *  name,
int32  index,
const char *  defaultValue 
) const

Return the string from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt16() [1/2]

uint16 BMessage::GetUInt16 ( const char *  name,
uint16  defaultValue 
) const

Return the uint16 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt16() [2/2]

uint16 BMessage::GetUInt16 ( const char *  name,
int32  index,
uint16  defaultValue 
) const

Return the uint16 value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt32() [1/2]

uint32 BMessage::GetUInt32 ( const char *  name,
uint32  defaultValue 
) const

Return the uint32 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt32() [2/2]

uint32 BMessage::GetUInt32 ( const char *  name,
int32  index,
uint32  defaultValue 
) const

Return the uint32 value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt64() [1/2]

uint64 BMessage::GetUInt64 ( const char *  name,
uint64  defaultValue 
) const

Return the uint64 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt64() [2/2]

uint64 BMessage::GetUInt64 ( const char *  name,
int32  index,
uint64  defaultValue 
) const

Return the uint64 value from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt8() [1/2]

uint8 BMessage::GetUInt8 ( const char *  name,
uint8  defaultValue 
) const

Return the uint8 value from message with name, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ GetUInt8() [2/2]

uint8 BMessage::GetUInt8 ( const char *  name,
int32  index,
uint8  defaultValue 
) const

Return the uint8 message from message with name and index, or defaultValue if not found.

Parameters
nameThe name of the item to retrieve.
indexThe index of the item to retrieve if there is more than one.
defaultValueThe value to use if the item specified by name is not found.
Returns
The item with name, or defaultValue if not found.
Since
Haiku R1

◆ HasBool()

bool BMessage::HasBool ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasData()

bool BMessage::HasData ( const char *  name,
type_code  ,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasDouble()

bool BMessage::HasDouble ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasFlat() [1/2]

bool BMessage::HasFlat ( const char *  name,
const BFlattenable object 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasFlat() [2/2]

bool BMessage::HasFlat ( const char *  name,
int32  n,
const BFlattenable object 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasFloat()

bool BMessage::HasFloat ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasInt16()

bool BMessage::HasInt16 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasInt32()

bool BMessage::HasInt32 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasInt64()

bool BMessage::HasInt64 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasInt8()

bool BMessage::HasInt8 ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasMessage()

bool BMessage::HasMessage ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasMessenger()

bool BMessage::HasMessenger ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasPoint()

bool BMessage::HasPoint ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasPointer()

bool BMessage::HasPointer ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasRect()

bool BMessage::HasRect ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasRef()

bool BMessage::HasRef ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ HasSpecifiers()

bool BMessage::HasSpecifiers ( ) const

Undocumented.

Since
BeOS R3

◆ HasString()

bool BMessage::HasString ( const char *  name,
int32  n = 0 
) const

Deprecated.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ IsEmpty()

bool BMessage::IsEmpty ( ) const

Check if the message has data members.

Returns
If this message contains data members, this method will return true, else it will return false.
See also
MakeEmpty()
Since
BeOS R3

◆ IsReply()

bool BMessage::IsReply ( ) const

Check if the message is a reply to a (previous) message.

Returns
If this message is a reply, this method will return true.
Since
BeOS R3

◆ IsSourceRemote()

bool BMessage::IsSourceRemote ( ) const

Check if the message is sent by another application.

Since
BeOS R3

◆ IsSourceWaiting()

bool BMessage::IsSourceWaiting ( ) const

Check if the sender expects a reply.

This method will return true, if the sender flagged that it is waiting for a reply, and such a reply has not yet been sent.

Since
BeOS R3

◆ IsSystem()

bool BMessage::IsSystem ( ) const

Check if the message is a system message.

Returns
If this message is a system message, the method will return true.
Since
BeOS R3

◆ MakeEmpty()

status_t BMessage::MakeEmpty ( )

Clear all data and metadata in this message.

Everything is cleared out, all labels and all associated data, as well as metadata such as reply info.

Returns
This method always returns B_OK.
See also
RemoveData()
RemoveName()
Since
BeOS R3

◆ operator delete()

void BMessage::operator delete ( void *  pointer,
size_t  size 
)

Frees memory allocated by new.

Warning
This method is deprecated, do not use.
Since
BeOS R5

◆ operator new() [1/2]

void * BMessage::operator new ( size_t  size)

Allocates size bytes of memory for a BMessage.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ operator new() [2/2]

void * BMessage::operator new ( size_t  ,
void *  pointer 
)

Allocates size bytes of memory for a BMessage.

Warning
This method is deprecated, do not use.
Since
BeOS R3

◆ operator=()

BMessage & BMessage::operator= ( const BMessage other)

Copy one message into another.

See the copy constructor, BMessage(const BMessage& other), for details on what is copied, and what isn't.

Since
BeOS R3

◆ PopSpecifier()

status_t BMessage::PopSpecifier ( )

Undocumented.

Since
BeOS R3

◆ Previous()

const BMessage * BMessage::Previous ( ) const

Get the message to which this message is a reply.

Returns
Returns a new BMessage with the same data stuctures as the message to which this message is a reply. You get the ownership of this message, so free it when you're done. If this message isn't a reply to another message, this method will return NULL.
Since
BeOS R3

◆ PrintToStream()

void BMessage::PrintToStream ( ) const

Print the message to the standard output.

This method can be used to debug your application. It can be used to check if it creates the messages properly, by checking if all the required fields are present, and it can be used to debug your message handling routines, especially the handling of those that are sent by external applications, to see if you understand the semantics correctly.

Since
BeOS R3

◆ RemoveData()

status_t BMessage::RemoveData ( const char *  name,
int32  index = 0 
)

Remove data associated with name at a specified index.

If this is the only instance of the data, then the entire label will be removed. This means you can recreate it with another type.

Parameters
nameThe name of which the associated data should be cleared.
indexThe index of the item that should be cleared.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe data has been removed.
B_BAD_VALUEThe index is less than 0.
B_BAD_INDEXThe index is out of bounds.
B_NAME_NOT_FOUNDThe name does not have any data associated with it.
See also
RemoveName()
MakeEmpty()
Since
BeOS R3

◆ RemoveName()

status_t BMessage::RemoveName ( const char *  name)

Remove all data associated with a name.

This also removes the label, so that you can recreate it with another type, if you want to.

Parameters
nameThe name that refers to the data you want to clear out.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKAll the data is removed.
B_BAD_VALUEThe name pointer points to NULL.
B_NAME_NOT_FOUNDThe name does not exist in this message.
See also
RemoveData()
MakeEmpty()
Since
BeOS R3

◆ Rename()

status_t BMessage::Rename ( const char *  oldEntry,
const char *  newEntry 
)

Rename a data label.

Parameters
oldEntryThe name of the label you want to rename.
newEntryThe new name of the data entry.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKRenaming succeeded.
B_BAD_VALUEEither the oldEntry or the newEntry pointers are NULL.
B_NAME_NOT_FOUNDThere is no data associated with the label oldEntry.
Since
Haiku R1

◆ ReplaceBool() [1/2]

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

Replace a boolean at the label name.

This method is an overloaded method of ReplaceBool(const char*, int32, bool). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aBooleanWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceBool() [2/2]

status_t BMessage::ReplaceBool ( const char *  name,
int32  index,
bool  aBoolean 
)

Replace a boolean at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_BOOL_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aBooleanWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceBool(const char*, bool)
Since
BeOS R5

◆ ReplaceColor() [1/2]

status_t BMessage::ReplaceColor ( const char *  name,
rgb_color  aColor 
)

Replace a color at the label name.

This method is an overloaded method of ReplaceColor(const char*, int32, rgb_color). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aColorWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
Haiku R1

◆ ReplaceColor() [2/2]

status_t BMessage::ReplaceColor ( const char *  name,
int32  index,
rgb_color  aColor 
)

Replace a rgb_color at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_RGB_32_BIT_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aColorWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceColor(const char*, rgb_color)
Since
Haiku R1

◆ ReplaceData() [1/2]

status_t BMessage::ReplaceData ( const char *  name,
type_code  type,
const void *  data,
ssize_t  numBytes 
)

Replace the data at label name.

This method is an overloaded method that replaces the data at index 0. See ReplaceData(const char*, type_code, int32, const void*, ssize_t).

Parameters
nameThe name associated with the data to replace.
typeThe type of the data.
dataA pointer to the new data that needs to be copied into the message.
numBytesThe size of the new data.
Returns
A status code, B_OK on success or an error code.
Since
BeOS R3

◆ ReplaceData() [2/2]

status_t BMessage::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.

The conditions for replacing data are that thename is correct, the type matches and the data entry at index exists.

There is also a collection of convenience methods, that allow you to efficiently replace rectanges (ReplaceRect()), booleans (ReplaceBool()), and so on.

Parameters
nameThe name associated with the data to replace.
typeThe type of the data.
indexThe index in the array to replace.
dataA pointer to the new data that needs to be copied into the message.
numBytesThe size of the new data.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_VALUEOne of the input parameters are invalid. Check that you did not pass NULL, and in case the field has fixed sized data, check that numBytes is the same as the specified fixed size.
B_BAD_INDEXThe index is out of range.
Since
BeOS R3

◆ ReplaceDouble() [1/2]

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

Replace a double at the label name.

This method is an overloaded method of ReplaceDouble(const char*, int32, double). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aDoubleWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceDouble() [2/2]

status_t BMessage::ReplaceDouble ( const char *  name,
int32  index,
double  aDouble 
)

Replace a double at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_DOUBLE_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aDoubleWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceDouble(const char*, double)
Since
BeOS R3

◆ ReplaceFlat() [1/2]

status_t BMessage::ReplaceFlat ( const char *  name,
BFlattenable object 
)

Replace a flattened object at the label name.

This method is an overloaded method of ReplaceFlat(const char*, int32, BFlattenable*).

It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
objectThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceFlat() [2/2]

status_t BMessage::ReplaceFlat ( const char *  name,
int32  index,
BFlattenable object 
)

Replace a flattened object at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the type returned by your object. This method uses BFlattenable::TypeCode() to determine the type of the object.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
objectThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceFlat(const char*, BFlattenable*)
Since
BeOS R3

◆ ReplaceFloat() [1/2]

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

Replace a float at the label name.

This method is an overloaded method of ReplaceFloat(const char*, int32, float). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aFloatThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceFloat() [2/2]

status_t BMessage::ReplaceFloat ( const char *  name,
int32  index,
float  aFloat 
)

Replace a float at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_FLOAT_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aFloatThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceFloat(const char*, float)
Since
BeOS R3

◆ ReplaceInt16() [1/2]

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

Replace an integer at the label name.

This method is an overloaded method of ReplaceInt16(const char*, int32, int16). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
valueWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceInt16() [2/2]

status_t BMessage::ReplaceInt16 ( const char *  name,
int32  index,
int16  value 
)

Replace an integer at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_INT16_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
valueWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceInt16(const char*, int16)
Since
BeOS R3

◆ ReplaceInt32() [1/2]

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

Replace an integer at the label name.

This method is an overloaded method of ReplaceInt8(const char*, int32, int32). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
valueWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceInt32() [2/2]

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

Replace an integer at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_INT32_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
valueThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceInt32(const char*, int32)
Since
BeOS R3

◆ ReplaceInt64() [1/2]

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

Replace an integer at the label name.

This method is an overloaded method of ReplaceInt8(const char*, int32, int64). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
valueWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceInt64() [2/2]

status_t BMessage::ReplaceInt64 ( const char *  name,
int32  index,
int64  value 
)

Replace an integer at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_INT64_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
valueThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceInt64(const char*, int64)
Since
BeOS R3

◆ ReplaceInt8() [1/2]

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

Replace an integer at the label name.

This method is an overloaded method of ReplaceInt8(const char*, int32, int8). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
valueWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceInt8() [2/2]

status_t BMessage::ReplaceInt8 ( const char *  name,
int32  index,
int8  value 
)

Replace an integer at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_INT8_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
valueWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceInt8(const char*, int8)
Since
BeOS R3

◆ ReplaceMessage() [1/2]

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

Replace a message at the label name.

This method is an overloaded method of ReplaceMessage(const char*, int32, BMessage*). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
messageThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceMessage() [2/2]

status_t BMessage::ReplaceMessage ( const char *  name,
int32  index,
const BMessage message 
)

Replace a message at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_MESSAGE_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
messageThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceMessage(const char*, BMessage*)
Since
BeOS R3

◆ ReplaceMessenger() [1/2]

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

Replace a messenger at the label name.

This method is an overloaded method of ReplaceMessenger(const char*, int32, BMessenger). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
messengerThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceMessenger() [2/2]

status_t BMessage::ReplaceMessenger ( const char *  name,
int32  index,
BMessenger  messenger 
)

Replace a messenger at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_MESSENGER_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
messengerThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceMessenger(const char*, BMessenger)
Since
BeOS R3

◆ ReplacePoint() [1/2]

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

Replace a point at the label name.

This method is an overloaded method of ReplacePoint(const char*, int32, BPoint). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aPointThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplacePoint() [2/2]

status_t BMessage::ReplacePoint ( const char *  name,
int32  index,
BPoint  aPoint 
)

Replace a point at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_POINT_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aPointThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplacePoint(const char*, aPoint)
Since
BeOS R3

◆ ReplacePointer() [1/2]

status_t BMessage::ReplacePointer ( const char *  name,
const void *  pointer 
)

Replace a pointer at the label name.

This method is an overloaded method of ReplacePointer(const char*, int32, const void*). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
pointerWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplacePointer() [2/2]

status_t BMessage::ReplacePointer ( const char *  name,
int32  index,
const void *  pointer 
)

Replace a pointer at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_POINTER_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
pointerWhere to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplacePointer(const char*, const void*)
Since
BeOS R3

◆ ReplaceRect() [1/2]

status_t BMessage::ReplaceRect ( const char *  name,
BRect  aRect 
)

Replace a rectangle at the label name.

This method is an overloaded method of ReplaceRect(const char*, int32, BRect). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aRectThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe object now contains the requested data.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceRect() [2/2]

status_t BMessage::ReplaceRect ( const char *  name,
int32  index,
BRect  aRect 
)

Replace a rectangle at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_RECT_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aRectThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceRect(const char*, BRect)
Since
BeOS R3

◆ ReplaceRef() [1/2]

status_t BMessage::ReplaceRef ( const char *  name,
const entry_ref ref 
)

Replace a reference to a file at the label name.

This method is an overloaded method of ReplaceRef(const char*, int32, entry_ref*). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
refThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceRef() [2/2]

status_t BMessage::ReplaceRef ( const char *  name,
int32  index,
const entry_ref ref 
)

Replace a reference to a file at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_REF_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
refThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceRef(const char*, entry_ref*)
Since
BeOS R3

◆ ReplaceString() [1/4]

status_t BMessage::ReplaceString ( const char *  name,
const char *  aString 
)

Replace a string at the label name.

This method is an overloaded method of ReplaceString(const char*, int32, const char*). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aStringThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R3

◆ ReplaceString() [2/4]

status_t BMessage::ReplaceString ( const char *  name,
int32  index,
const char *  aString 
)

Replace a string at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_STRING_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aStringThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceString(const char*, const char*)
Since
BeOS R3

◆ ReplaceString() [3/4]

status_t BMessage::ReplaceString ( const char *  name,
const BString aString 
)

Replace a string at the label name.

This method is an overloaded method of ReplaceString(const char*, int32, BString&). It replaces the data at index 0.

Parameters
nameThe name associated with the data to replace.
aStringThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_NAME_NOT_FOUNDThere is no field with this name.
Since
BeOS R5

◆ ReplaceString() [4/4]

status_t BMessage::ReplaceString ( const char *  name,
int32  index,
const BString aString 
)

Replace a string at the label name at a specified index.

The data at the specified name and index will be replaced, if it matches the B_STRING_TYPE.

Parameters
nameThe name associated with the data to replace.
indexThe index in the array to replace.
aStringThe object to store in the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe operation succeeded.
B_BAD_INDEXThe index was out of range.
B_NAME_NOT_FOUNDThere is no field with this name.
See also
ReplaceString(const char*, BString&)
Since
BeOS R5

◆ ReturnAddress()

BMessenger BMessage::ReturnAddress ( ) const

Get a messenger that points to the sender of the message.

Using this method, you can fetch a BMessenger that can be used to deliver replies to this message. This method works both for local and remote deliveries.

For remote deliveries, this approach is preferred over sending the reply using a standard BMessenger that is created with the signature of the application. A standard BMessenger sends the messages to the main BLooper of the application, the BApplication object. With the delivery data stored in the messages, the reply using this messenger will be directed at a specific looper that is able to handle the replies.

If this method is called on a message that has not been delivered (yet), it will return an empty BMessenger object.

Since
BeOS R3

◆ SendReply() [1/5]

status_t BMessage::SendReply ( uint32  command,
BHandler replyTo = NULL 
)

Asynchronously send a reply to this message.

This is an overloaded member of SendReply(BMessage*, BMessenger, bigtime_t). Use this variant if you want to send a message without data members.

Since
BeOS R3

◆ SendReply() [2/5]

status_t BMessage::SendReply ( BMessage reply,
BHandler replyTo = NULL,
bigtime_t  timeout = B_INFINITE_TIMEOUT 
)

Asynchronously send a reply to this message.

This is an overloaded member of SendReply(BMessage*, BMessenger, bigtime_t). Use this variant if you want to send the message to a specific handler (instead of a complete messenger).

Since
BeOS R3

◆ SendReply() [3/5]

status_t BMessage::SendReply ( BMessage reply,
BMessenger  replyTo,
bigtime_t  timeout = B_INFINITE_TIMEOUT 
)

Asynchronously send a reply to this message.

This method sends a reply to this message to the sender. On your turn, you specify a messenger that handles a reply back to the message you specify as the reply argument. You can set a timeout for the message to be delivered. This method blocks until the message has been received, or the timeout has been reached.

Parameters
replyThe message that is in reply to this message.
replyToIn case the receiver needs to reply to the message you are sending, you can specify the return address with this argument.
timeoutThe maximum time in microseconds this delivery may take. The timeout is a relative timeout. You can also use B_INFINITE_TIMEOUT if you want to wait infinitely for the message to be delivered.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe message has been delivered.
B_DUPLICATE_REPLYThere already has been a reply to this message.
B_BAD_PORT_IDThe reply address is not valid (anymore).
B_WOULD_BLOCKThe delivery timeout was B_INFINITE_TIMEOUT (0) and the target port was full when trying to deliver the message.
B_TIMED_OUTThe timeout expired while trying to deliver the message.
See also
SendReply(uint32 command, BHandler* replyTo)
Since
Haiku R1

◆ SendReply() [4/5]

status_t BMessage::SendReply ( uint32  command,
BMessage replyToReply 
)

Synchronously send a reply to this message, and wait for a reply back.

This is an overloaded member of SendReply(BMessage*, BMessage*, bigtime_t, bigtime_t) Use this variant if you want to send a message without data members.

Since
BeOS R3

◆ SendReply() [5/5]

status_t BMessage::SendReply ( BMessage 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.

This method sends a reply to this message to the sender. The reply is delivered, and then the method waits for a reply from the receiver. If a reply is received, that reply is copied into the replyToReply argument. If the message was delivered properly, but the receiver did not reply within the specified replyTimeout, the what member of replyToReply will be set to B_NO_REPLY.

Parameters
replyThe message that is in reply to this message.
[out]replyToReplyThe reply is copied into this argument.
sendTimeoutThe maximum time in microseconds this delivery may take. The timeout is a relative timeout. You can also use B_INFINITE_TIMEOUT if you want to wait infinitely for the message to be delivered.
replyTimeoutThe maximum time in microseconds you want to wait for a reply. Note that the timer starts when the message has been delivered.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe message has been delivered.
B_DUPLICATE_REPLYThere already has been a reply to this message.
B_BAD_VALUEEither reply or replyToReply is NULL.
B_BAD_PORT_IDThe reply address is not valid (anymore).
B_WOULD_BLOCKThe delivery timeout was B_INFINITE_TIMEOUT (0) and the target port was full when trying to deliver the message.
B_TIMED_OUTThe timeout expired while trying to deliver the message.
B_NO_MORE_PORTSAll reply ports are in use.
See also
SendReply(uint32 command, BMessage* replyToReply)
Since
BeOS R3

◆ SetCurrentSpecifier()

status_t BMessage::SetCurrentSpecifier ( int32  index)

Undocumented.

Since
Haiku R1

◆ Unflatten() [1/2]

status_t BMessage::Unflatten ( const char *  flatBuffer)

Unflatten a message from a buffer and put it into the current object.

This action clears the current contents of the message.

Parameters
flatBufferThe buffer that contains the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe buffer has been unflattened.
B_BAD_VALUEThe buffer does not contain a valid message.
B_NO_MEMORYAn error occured whilst allocating memory for the data members.
See also
Flatten(char* buffer, ssize_t size) const
Unflatten(BDataIO* stream)
Since
BeOS R3

◆ Unflatten() [2/2]

status_t BMessage::Unflatten ( BDataIO stream)

Unflatten a message from a stream and put it into the current object.

This action clears the current contents of the message.

Parameters
streamThe stream that contains the message.
Returns
A status code, B_OK on success or an error code.
Return values
B_OKThe message has been unflattened.
B_BAD_VALUEThe stream does not contain a valid message.
B_NO_MEMORYAn error occured whilst allocating memory for the data members.
See also
Flatten(BDataIO* stream, ssize_t* size) const
Unflatten(const char*)
Since
BeOS R3

◆ WasDelivered()

bool BMessage::WasDelivered ( ) const

Check if this message was delivered through the delivery methods.

If this message is passed via a BMessenger or BLooper::PostMessage(), this method will return true.

Warning
This method should not be abused by a thread that sends a message to track whether or not a message was delivered. This is because the ownership of the message goes to the receiving looper, which will delete the message as soon as it is done with it.
If you need to check whether a message is delivered, you should either ask for a reply, or use one of the synchronous BMessenger::SendMessage() methods.
Since
BeOS R3

◆ WasDropped()

bool BMessage::WasDropped ( ) const

Check if the message was delivered through 'drag and drop'.

Returns
This method returns true if the message has been delivered through drag and drop. It returns false if it has been delivered through the regular messaging functions, or if the message has not been delivered at all.
See also
DropPoint()
Since
BeOS R3

Member Data Documentation

◆ what

BMessage::what

A 4-byte constant that determines the type of message.

You can directly manipulate this data member.

Since
BeOS R3