BMessage Class Reference

#include <Message.h>

Inheritance diagram for BMessage:

BAppPrefs BResourceSet::MessageObject List of all members.

Detailed Description

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

See also:
Using BMessage

Data Members

uint32 what A coded constant that captures what the message is about.


Public Member Functions

 BMessage ()
 BMessage (uint32 what)
 BMessage (const BMessage &a_message)
virtual ~BMessage ()
BMessageoperator= (const BMessage &msg)
status_t Update (const BMessage &from, bool recursive=false)
status_t FillIn (const BMessage &from, bool recursive=false)
status_t GetInfo (type_code typeRequested, int32 which, const char **name, type_code *typeReturned, int32 *count=NULL) const
status_t GetInfo (const char *name, type_code *type, int32 *c=0) const
status_t GetInfo (const char *name, type_code *type, bool *fixed_size) const
status_t GetNextName (void **cookie, const char **outName, type_code *outType=NULL, int32 *outCount=NULL) const
int32 CountNames (type_code type) const
bool IsEmpty () const
bool IsSystem () const
bool IsReply () const
void PrintToStream () const
status_t Rename (const char *old_entry, const char *new_entry)
bool WasDelivered () const
bool IsReplyRequested () const
bool IsSourceWaiting () const
bool IsSourceRemote () const
bool CompareDestination (const BMessenger &test) const
BMessenger ReturnAddress () const
const BMessagePrevious () const
bool WasDropped () const
BPoint DropPoint (BPoint *offset=NULL) const
bool HasWhen () const
bigtime_t When () const
void SetWhen (bigtime_t time)
status_t SendReply (const BMessage &the_reply, const BMessenger &reply_to, uint32 flags=B_TIMEOUT, bigtime_t timeout=B_INFINITE_TIMEOUT)
status_t SendReply (uint32 command)
status_t SendReply (uint32 command, const BMessenger &reply_to)
status_t SendReply (const BMessage &the_reply, BMessage *reply_to_reply, uint32 flags=B_TIMEOUT, bigtime_t send_timeout=B_INFINITE_TIMEOUT, bigtime_t reply_timeout=B_INFINITE_TIMEOUT)
status_t SendReply (uint32 command, BMessage *reply_to_reply)
status_t SendReply (uint32 command, BHandler *reply_to)
status_t SendReply (BMessage *the_reply, BHandler *reply_to=NULL, bigtime_t timeout=B_INFINITE_TIMEOUT)
status_t SendReply (BMessage *the_reply, BMessenger reply_to, bigtime_t timeout=B_INFINITE_TIMEOUT)
status_t SendReply (BMessage *the_reply, BMessage *reply_to_reply, bigtime_t send_timeout=B_INFINITE_TIMEOUT, bigtime_t reply_timeout=B_INFINITE_TIMEOUT)
ssize_t FlattenedSize () const
status_t Flatten (char *buffer, ssize_t size) const
status_t Flatten (BDataIO *stream, ssize_t *size=NULL) const
status_t Unflatten (const char *flat_buffer)
status_t Unflatten (BDataIO *stream)
ssize_t FlattenedSize (message_version format) const
status_t Flatten (message_version format, char *buffer, ssize_t size) const
status_t Flatten (message_version format, BDataIO *stream, ssize_t *size=NULL) const
status_t WritePort (port_id port, int32 code, uint32 flags=0, bigtime_t timeout=B_INFINITE_TIMEOUT) const
status_t ReadPort (port_id port, ssize_t size=-1, int32 *outCode=NULL, uint32 flags=0, bigtime_t timeout=B_INFINITE_TIMEOUT)
size_t RawPortSize () const
const void * RawPortData () const
status_t AddSpecifier (const char *property)
status_t AddSpecifier (const char *property, int32 index)
status_t AddSpecifier (const char *property, int32 index, int32 range)
status_t AddSpecifier (const char *property, const char *name)
status_t AddSpecifier (const BMessage *specifier)
status_t SetCurrentSpecifier (int32 index)
status_t GetCurrentSpecifier (int32 *index, BMessage *specifier=NULL, int32 *form=NULL, const char **property=NULL) const
bool HasSpecifiers () const
status_t PopSpecifier ()
status_t AddRect (const char *name, BRect a_rect)
status_t AddPoint (const char *name, BPoint a_point)
status_t AddString (const char *name, const char *a_string)
status_t AddString (const char *name, const BString &a_string)
status_t AddInt8 (const char *name, int8 val)
status_t AddInt16 (const char *name, int16 val)
status_t AddInt32 (const char *name, int32 val)
status_t AddInt64 (const char *name, int64 val)
status_t AddBool (const char *name, bool a_boolean)
status_t AddFloat (const char *name, float a_float)
status_t AddDouble (const char *name, double a_double)
status_t AddRGBColor (const char *name, rgb_color a_color, type_code type=B_RGB_COLOR_TYPE)
status_t AddPointer (const char *name, const void *ptr)
status_t AddMessenger (const char *name, BMessenger messenger)
status_t AddRef (const char *name, const entry_ref *ref)
status_t AddMessage (const char *name, const BMessage *msg)
status_t AddFlat (const char *name, const BFlattenable *obj, int32 count=1)
status_t AddAtom (const char *name, const BAtom *atm)
status_t AddAtomRef (const char *name, const BAtom *atm)
status_t AddData (const char *name, type_code type, const void *data, ssize_t numBytes, bool is_fixed_size=true, int32 count=1)
status_t RemoveData (const char *name, int32 index=0)
status_t RemoveName (const char *name)
status_t MakeEmpty ()
status_t FindRect (const char *name, BRect *rect) const
status_t FindRect (const char *name, int32 index, BRect *rect) const
status_t FindPoint (const char *name, BPoint *pt) const
status_t FindPoint (const char *name, int32 index, BPoint *pt) const
status_t FindString (const char *name, const char **str) const
status_t FindString (const char *name, int32 index, const char **str) const
status_t FindString (const char *name, BString *str) const
status_t FindString (const char *name, int32 index, BString *str) const
status_t FindInt8 (const char *name, int8 *value) const
status_t FindInt8 (const char *name, int32 index, int8 *val) const
status_t FindInt16 (const char *name, int16 *value) const
status_t FindInt16 (const char *name, int32 index, int16 *val) const
status_t FindInt32 (const char *name, int32 *value) const
status_t FindInt32 (const char *name, int32 index, int32 *val) const
status_t FindInt64 (const char *name, int64 *value) const
status_t FindInt64 (const char *name, int32 index, int64 *val) const
status_t FindBool (const char *name, bool *value) const
status_t FindBool (const char *name, int32 index, bool *value) const
status_t FindFloat (const char *name, float *f) const
status_t FindFloat (const char *name, int32 index, float *f) const
status_t FindDouble (const char *name, double *d) const
status_t FindDouble (const char *name, int32 index, double *d) const
status_t FindRGBColor (const char *name, rgb_color *c, bool allow_int32_type=false) const
status_t FindRGBColor (const char *name, int32 index, rgb_color *c, bool allow_int32_type=false) const
status_t FindAtom (const char *name, BAtom **atm) const
status_t FindAtom (const char *name, int32 index, BAtom **atm) const
status_t FindAtomRef (const char *name, BAtom **atm) const
status_t FindAtomRef (const char *name, int32 index, BAtom **atm) const
status_t FindPointer (const char *name, void **ptr) const
status_t FindPointer (const char *name, int32 index, void **ptr) const
status_t FindMessenger (const char *name, BMessenger *m) const
status_t FindMessenger (const char *name, int32 index, BMessenger *m) const
status_t FindRef (const char *name, entry_ref *ref) const
status_t FindRef (const char *name, int32 index, entry_ref *ref) const
status_t FindMessage (const char *name, BMessage *msg) const
status_t FindMessage (const char *name, int32 index, BMessage *msg) const
status_t FindFlat (const char *name, BFlattenable *obj) const
status_t FindFlat (const char *name, int32 index, BFlattenable *obj) const
status_t FindData (const char *name, type_code type, const void **data, ssize_t *numBytes) const
status_t FindData (const char *name, type_code type, int32 index, const void **data, ssize_t *numBytes) const
status_t ReplaceRect (const char *name, BRect a_rect)
status_t ReplaceRect (const char *name, int32 index, BRect a_rect)
status_t ReplacePoint (const char *name, BPoint a_point)
status_t ReplacePoint (const char *name, int32 index, BPoint a_point)
status_t ReplaceString (const char *name, const char *string)
status_t ReplaceString (const char *name, int32 index, const char *string)
status_t ReplaceString (const char *name, const BString &string)
status_t ReplaceString (const char *name, int32 index, const BString &string)
status_t ReplaceInt8 (const char *name, int8 val)
status_t ReplaceInt8 (const char *name, int32 index, int8 val)
status_t ReplaceInt16 (const char *name, int16 val)
status_t ReplaceInt16 (const char *name, int32 index, int16 val)
status_t ReplaceInt32 (const char *name, int32 val)
status_t ReplaceInt32 (const char *name, int32 index, int32 val)
status_t ReplaceInt64 (const char *name, int64 val)
status_t ReplaceInt64 (const char *name, int32 index, int64 val)
status_t ReplaceBool (const char *name, bool a_bool)
status_t ReplaceBool (const char *name, int32 index, bool a_bool)
status_t ReplaceFloat (const char *name, float a_float)
status_t ReplaceFloat (const char *name, int32 index, float a_float)
status_t ReplaceDouble (const char *name, double a_double)
status_t ReplaceDouble (const char *name, int32 index, double a_double)
status_t ReplaceRGBColor (const char *name, rgb_color a_color, bool allow_int32_type=false)
status_t ReplaceRGBColor (const char *name, int32 index, rgb_color a_color, bool allow_int32_type=false)
status_t ReplaceAtom (const char *name, const BAtom *atm)
status_t ReplaceAtom (const char *name, int32 index, const BAtom *atm)
status_t ReplaceAtomRef (const char *name, const BAtom *atm)
status_t ReplaceAtomRef (const char *name, int32 index, const BAtom *atm)
status_t ReplacePointer (const char *name, const void *ptr)
status_t ReplacePointer (const char *name, int32 index, const void *ptr)
status_t ReplaceMessenger (const char *name, BMessenger messenger)
status_t ReplaceMessenger (const char *name, int32 index, BMessenger msngr)
status_t ReplaceRef (const char *name, const entry_ref *ref)
status_t ReplaceRef (const char *name, int32 index, const entry_ref *ref)
status_t ReplaceMessage (const char *name, const BMessage *msg)
status_t ReplaceMessage (const char *name, int32 index, const BMessage *msg)
status_t ReplaceFlat (const char *name, const BFlattenable *obj)
status_t ReplaceFlat (const char *name, int32 index, const BFlattenable *obj)
status_t ReplaceData (const char *name, type_code type, const void *data, ssize_t data_size)
status_t ReplaceData (const char *name, type_code type, int32 index, const void *data, ssize_t data_size)
void * operator new (size_t size)
void * operator new (size_t size, const std::nothrow_t &)
void * operator new (size_t, void *arg)
void operator delete (void *ptr, size_t size)
bool HasRect (const char *, int32 n=0) const
bool HasPoint (const char *, int32 n=0) const
bool HasString (const char *, int32 n=0) const
bool HasInt8 (const char *, int32 n=0) const
bool HasInt16 (const char *, int32 n=0) const
bool HasInt32 (const char *, int32 n=0) const
bool HasInt64 (const char *, int32 n=0) const
bool HasBool (const char *, int32 n=0) const
bool HasFloat (const char *, int32 n=0) const
bool HasDouble (const char *, int32 n=0) const
bool HasRGBColor (const char *name, int32 n=0, bool allow_int32_type=false) const
bool HasAtom (const char *, int32 n=0) const
bool HasAtomRef (const char *, int32 n=0) const
bool HasPointer (const char *, int32 n=0) const
bool HasMessenger (const char *, int32 n=0) const
bool HasRef (const char *, int32 n=0) const
bool HasMessage (const char *, int32 n=0) const
bool HasFlat (const char *, const BFlattenable *) const
bool HasFlat (const char *, int32, const BFlattenable *) const
bool HasData (const char *, type_code, int32 n=0) const
BRect FindRect (const char *, int32 n=0) const
BPoint FindPoint (const char *, int32 n=0) const
const char * FindString (const char *, int32 n=0) const
int8 FindInt8 (const char *, int32 n=0) const
int16 FindInt16 (const char *, int32 n=0) const
int32 FindInt32 (const char *, int32 n=0) const
int64 FindInt64 (const char *, int32 n=0) const
bool FindBool (const char *, int32 n=0) const
float FindFloat (const char *, int32 n=0) const
double FindDouble (const char *, int32 n=0) const
status_t AddAtom (const char *name, const atom< BAtom > &obj)
status_t AddAtomRef (const char *name, const atom< BAtom > &obj)
status_t AddAtomRef (const char *name, const atomref< BAtom > &obj)
status_t FindAtom (const char *name, atom< BAtom > &atm) const
status_t FindAtom (const char *name, int32 index, atom< BAtom > &atm) const
status_t FindAtomRef (const char *name, atomref< BAtom > &atm) const
status_t FindAtomRef (const char *name, int32 index, atomref< BAtom > &atm) const
status_t ReplaceAtom (const char *name, const atom< BAtom > &atm)
status_t ReplaceAtom (const char *name, int32 index, const atom< BAtom > &atm)
status_t ReplaceAtomRef (const char *name, const atomref< BAtom > &atm)
status_t ReplaceAtomRef (const char *name, int32 index, const atomref< BAtom > &atm)
template<class TYPE>
status_t FindAtom (const char *name, atom< TYPE > &atm) const
template<class TYPE>
status_t FindAtom (const char *name, int32 index, atom< TYPE > &atm) const
template<class TYPE>
status_t FindAtomRef (const char *name, atomref< TYPE > &atm) const
template<class TYPE>
status_t FindAtomRef (const char *name, int32 index, atomref< TYPE > &atm) const

Public Attributes

uint32 what

Friends

class BMessageList
class BMessenger
class BApplication
class BParcel
void _msg_cache_cleanup_ ()
BMessage_reconstruct_msg_ (uint32, uint32)
void _set_message_target_ (BMessage *, int32, bool)
void _set_message_reply_ (BMessage *, BMessenger)
int32 _get_message_target_ (BMessage *)
bool _use_preferred_target_ (BMessage *)
BDataIOoperator<< (BDataIO &io, const BMessage &message)
int _init_message_ ()
int _delete_message_ ()


Constructor & Destructor Documentation

BMessage  ) 
 

Creates a new BMessage object.

BMessage uint32  pwhat  )  [explicit]
 

Creates a new BMessage object that has the given command constant.

Parameters:
pwhat command constant

BMessage const BMessage msg  ) 
 

Creates a new BMessage object hat's a copy of another BMessage. If it's a copy, the new object contains the same command constant and data fields as message.

Parameters:
msg BMessage

~BMessage  )  [virtual]
 

Frees all memory allocated to hold message data. If the message sender is expecting a reply but hasn't received one, a default reply (with B_NO_REPLY as the what data member) is sent before the message is destroyed.

The system retains ownership of the messages it delivers to you. Each message loop routinely deletes delivered BMessages after the application is finished responding to them.


Member Function Documentation

status_t AddAtom const char *  name,
const atom< BAtom > &  obj
 

status_t AddAtom const char *  name,
const BAtom atm
 

status_t AddAtomRef const char *  name,
const atomref< BAtom > &  obj
 

status_t AddAtomRef const char *  name,
const atom< BAtom > &  obj
 

status_t AddAtomRef const char *  name,
const BAtom atm
 

status_t AddBool const char *  name,
bool  a_boolean
 

Most of the other functions are variants of AddData() that hard-code the field's type. For example, AddFloat() assigns the type B_FLOAT_TYPE; AddBool() assigns B_BOOL_TYPE, and so on.

Parameters:
name 
a_boolean 

status_t AddData const char *  name,
type_code  type,
const void *  data,
ssize_t  numBytes,
bool  is_fixed_size = true,
int32  count = 1
 

These functions add data to the field named name and assign a data type to the field. Field names can be no longer than 255 characters. If more than one item of data is added under the same name, the BMessage creates an array of data for that name. Each time you add another value (to the same name), the value is added to the end of the array - you can't add a value at a specific index. A given field can only store one type of data.

Copies numBytes of data into the field, and assigns the data a type code. It copies whatever the param_ref data pointer points to. For example, if you want to add a string of characters to the message, data should be the string pointer (char *). If you want to add only the string pointer, not the characters themselves, data should be a pointer to the pointer (char **). The assigned type must be a specific data type; it should not be B_ANY_TYPE.

When you call AddData() to place the first item in an array under a new name, you can provide it with two arguments, fixedSize and numItems, that will improve the object's efficiency. If the fixedSize flag is true, each item in the array must have the same number of bytes; if the flag is false, items can vary in size. numItems tells the object to pre-allocate storage for some number of items. This isn't a limit - you can add more than numItems to the field.

Parameters:
name 
type 
data 
numBytes 
is_fixed_size (dafault is true)
count (default is 1)
Most of the other functions are variants of AddData() that hard-code the field's type. For example, AddFloat() assigns the type B_FLOAT_TYPE; AddBool() assigns B_BOOL_TYPE, and so on.

There's no limit on the number of named fields a message can contain or on the size of a field's data. However, since the search is linear, combing through a very long list of names to find a particular piece of data may be inefficient. Also, because of the amount of data that must be moved, an extremely large message can slow the delivery mechanism. It's sometimes better to put some of the information in a common location (a file, a private clipboard, a shared area of memory) and just refer to it in the message.

status_t AddDouble const char *  name,
double  a_double
 

status_t AddFlat const char *  name,
const BFlattenable obj,
int32  count = 1
 

Flattens an obj (by calling its Flatten() function) and adds the flat data to the message. It calls the object's TypeCode() function to learn the type code it should associate with the data. Objects that are added through AddFlat() must inherit from BFlattenable (defined in the Support Kit).

You can also provide a numItems hint to AddFlat() when you call it to set up a new array AddFlat() calls the object's IsFixedSize() function to discover whether all items in the array will be the same size.

Returns:
B_ERROR if the data is too massive to be added to the message

B_BAD_TYPE if the data can't be added to an existing array because it's the wrong type

B_NO_MEMORY if the BMessage can't get enough memory to hold the data

B_BAD_VALUE if the proposed name for the data is longer than 255 bytes.

If all goes well, they return B_OK.

status_t AddFloat const char *  name,
float  a_float
 

status_t AddInt16 const char *  name,
int16  val
 

status_t AddInt32 const char *  name,
int32  val
 

Takes an int32 or uint32.

Parameters:
name 
val 

status_t AddInt64 const char *  name,
int64  val
 

status_t AddInt8 const char *  name,
int8  val
 

status_t AddMessage const char *  name,
const BMessage msg
 

AddMessage() adds one BMessage to another.

status_t AddMessenger const char *  name,
BMessenger  messenger
 

Takes a BMessenger object.

Parameters:
name 
messenger 

status_t AddPoint const char *  name,
BPoint  a_point
 

status_t AddPointer const char *  name,
const void *  obj
 

Adds only the pointer it's passed, not the data it points to.

To accomplish the same thing, AddData() would take a pointer to the pointer. (The pointer will be valid only locally; it won't be useful to a remote destination.)

Parameters:
name 
obj 

status_t AddRect const char *  name,
BRect  r
 

Add Rectangle.

Parameters:
name 
r Rectangle

status_t AddRef const char *  name,
const entry_ref ref
 

Similarly, AddRef() adds the pointed to entry_ref structure to the message (and the variable-length name that's one of the elements of the structure);

status_t AddRGBColor const char *  name,
rgb_color  a_color,
type_code  type = B_RGB_COLOR_TYPE
 

status_t AddSpecifier const BMessage spec  )