Public Member Functions | Static Public Member Functions | List of all members
BArchivable Class Reference

Interface for objects that can be archived into a BMessage. More...

Inherited by BBitmap, BCollator, BCurrency, BCursor [private], BFormattingConventions, BGradient, BHandler, BLayoutItem, BListItem, BMenuItem, BNetAddress, BNetBuffer, BNetEndpoint, BNetworkCookie, BNetworkCookieJar, BNotification, BPicture, BShape, BTab, BToolTip, BTranslator, BTranslatorRoster, BUrl, and BUrlResult.

Public Member Functions

 BArchivable (BMessage *from)
 Constructor. Does important behind-the-scenes work in the unarchiving process. More...
 
 BArchivable ()
 Constructor. Does nothing. More...
 
virtual ~BArchivable ()
 Destructor. Does nothing. More...
 
virtual status_t AllArchived (BMessage *archive) const
 Method relating to the use of BArchiver. More...
 
virtual status_t AllUnarchived (const BMessage *archive)
 Method relating to the use of BUnarchiver. More...
 
virtual status_t Archive (BMessage *into, bool deep=true) const
 Archive the object into a BMessage. More...
 
virtual status_t Perform (perform_code d, void *arg)
 Perform some action (Internal method defined for binary compatibility purposes).
 

Static Public Member Functions

static BArchivableInstantiate (BMessage *archive)
 Static member to restore objects from messages. More...
 

Detailed Description

Interface for objects that can be archived into a BMessage.

BArchivable provides an interface for objects that can be put into message archives and extracted into objects in another location. Using this you are able to send objects between applications, or even between computers across networks.

BArchivable differs from BFlattenable in that BFlattenable is designed to store objects into flat streams of data, the main objective being storage to disk. The objective of this interface, however, is to store objects that will later be restored as new (but identical) objects. To illustrate this point, BArchivable objects can be restored automatically to the correct class, whereas BFlattenable objects have a data type which you need to map to classes manually.

Archiving is done with the Archive() method. If your class supports it, the caller can request it to store into a deep archive, meaning that all child objects in it will be stored. Extracting the archive works with the Instantiate() method, which is static. Since the interface is designed to extract objects without the caller knowing what kind of object it actually is, the global function instantiate_object() instantiates a message without you manually having to determine the class the message is from. This adds considerable flexibility and allows BArchivable to be used in combination with other add-ons.

To provide this interface in your classes you should publicly inherit this class. You should implement Archive() and Instantiate(), and provide one constructor that takes one BMessage argument.

If your class holds references to other BArchivable objects that you wish to archive, then you should consider using the BArchiver and BUnarchiver classes in your Archive() method and archive constructor, respectively. You should also consider implementing the AllArchived() and AllUnarchived() methods, which were designed to ease archiving and unarchiving in such a situation.

Since
BeOS R3

Constructor & Destructor Documentation

BArchivable::BArchivable ( BMessage from)

Constructor. Does important behind-the-scenes work in the unarchiving process.

If you inherit this interface you should provide at least one constructor that takes one BMessage argument. In that constructor, you should call your parent class' archive constructor (even if your parent class is BArchivable).

Since
BeOS R3
BArchivable::BArchivable ( )

Constructor. Does nothing.

Since
BeOS R3
BArchivable::~BArchivable ( )
virtual

Destructor. Does nothing.

Since
BeOS R3

Member Function Documentation

status_t BArchivable::AllArchived ( BMessage into) const
virtual

Method relating to the use of BArchiver.

This hook function is called once the first BArchiver that was created in an archiving session is either destroyed, or has its Finish() method called. Implementations of this method can be used, in conjunction with BArchiver::IsArchived(), to reference objects in your archive that you do not own, depending on whether or not those objects were archived by their owners. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning
To guarantee that your AllArchived() method will be called during archival, you must create a BArchiver object in your Archive() implementation.
You should archive any objects you own in your Archive() method implementation, and NOT your AllArchived() method.
See also
BArchiver BArchiver::Finish()
Since
Haiku R1

Reimplemented in BView, BAbstractSpinner, BTextControl, BMenuField, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, and BGroupLayout.

status_t BArchivable::AllUnarchived ( const BMessage archive)
virtual

Method relating to the use of BUnarchiver.

This hook function is called triggered in the BUnarchiver::Finish() method. In this method, you can rebuild references to objects that may be direct children of your object, or may be children of other objects. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning
To guarantee that your AllUnarchived() method will be called during unarchival, you must create a BUnarchiver object in your archive constructor.
See also
BUnarchiver, BUnarchiver::Finish()
Since
Haiku R1

Reimplemented in BView, BAbstractSpinner, BTabView, BTextControl, BMenuField, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, BGroupLayout, and BScrollView.

status_t BArchivable::Archive ( BMessage into,
bool  deep = true 
) const
virtual

Archive the object into a BMessage.

You should call this method from your derived implementation as it adds the data needed to instantiate your object to the message.

Parameters
intoThe message you store your object in.
deepIf true, all children of this object should be archived as well.
Return values
B_OKThe archive operation was successful.
B_BAD_VALUENULL archive message.
B_ERRORThe archive operation failed.
Since
BeOS R3

Reimplemented in BView, BWindow, BTabView, BCollator, BDirectWindow, BTextView, BBitmap, BLayout, BGridLayout, BLayoutItem, BMenu, BShape, BAlert, BCursor, BAbstractSpinner, BTranslatorRoster, BApplication, BListView, BMenuBar, BTwoDimensionalLayout, BLooper, BAbstractLayout, BControl, BGroupLayout, BHandler, BButton, BTextControl, BColorControl, BMenuField, BDragger, BScrollBar, BMenuItem, BPictureButton, BBox, BChannelControl, BScrollView, BTab, BOutlineListView, BRadioButton, BCheckBox, BListItem, BPicture, BToolTip, BStringView, BPopUpMenu, BSeparatorItem, and BStringItem.

static BArchivable * BArchivable::Instantiate ( BMessage archive)
static

Static member to restore objects from messages.

You should always check that the archive argument actually corresponds to your class. The automatic functions, such as instantiate_object() and BUnarchiver::InstantiateObject() will not choose the wrong class but manual calls to this member might be faulty. You can verify that archive stores an object of your class with the validate_instantiation() function.

Parameters
archiveThe message with the data of the object to restore.
Returns
A pointer to a BArchivable object.
Return values
Youshould return a pointer to the object you create with archive, or NULL if the unarchival fails.
Warning
The default implementation will always return NULL. Even though it is possible to store plain BArchivable objects, it is impossible to restore them.
See also
instantiate_object(BMessage*)
BUnarchiver::InstantiateObject()
Since
BeOS R3