BArchivable

Derived from: none
Declared in:  be/support/Archivable.h
Summary:  more...

BArchivable is a protocol for archiving and unarchiving objects. When you archive an object, you record its state into a BMessage that can be sent to another application, flattened and saved as a file, cached in memory, and so on. Unarchiving does the opposite: It takes a BMessage archive and turns it into a functioning object.

See "Archiving" for more information on the BeOS archival system.

Constructor and Destructor

BArchivable()

BArchivable(void) BArchivable(BMessage *archive)

Does nothing.

~BArchivable()

virtual ~BArchivable()

Does nothing.

Static Functions

Instantiate()

static BArchivable *Instantiate(BMessage *archive)

Derived classes should implement Instantiate() to return a new BArchivable object that was constructed from the BMessage archive. For example:

BArchivable *TheClass::Instantiate(BMessage *archive) {    if ( !validate_instantiation(archive, "TheClass") )       return NULL;    return new TheClass(archive); }

Instantiate() must return a BArchivable *, regardless of the actual class in which it's implemented.

This function depends on a constructor that can initialize the new object from the archive BMessage. See "Instantiability" for more information.

The default implementation returns NULL.

Member Functions

Archive()

virtual status_t Archive(BMessage *archive, bool deep = true) const

The default implementation adds the name of the object's class to archive's "class" field. Derived classes must override Archive() to augment this implementation by adding, to the BMessage, data that describes the current state of the object. Each implementation of this function should begin by incorporating the inherited version:

/* We'll assume that MyView inherits from BView. */ status_t MyView::Archive(BMessage *archive, bool deep) {    BView::Archive(archive, deep);    . . . }

If the class can be instantiated directly from a derived class, it should also add its name to the "class" array:

archive->AddString("class", "MyView");

The deep flag declares whether Archive() should include objects that "belong" to the archiving object. For example, a deep BView archive would include archived forms of the view's children.

Archive() should return B_OK if it's successful; otherwise, it should return B_ERROR or a more descriptive error code.