Public Member Functions | List of all members
BArchiver Class Reference

A class that simplifies the archiving of complicated BArchivable hierarchies. More...

Public Member Functions

 BArchiver (BMessage *archive)
 Constructs a BArchiver object that manages archive. More...
 
 ~BArchiver ()
 Destroys a BArchiver object. If the BArchiver object has not had its Finish() method called, this will be done now. More...
 
status_t AddArchivable (const char *name, BArchivable *archivable, bool deep=true)
 Adds a reference to archivable to the archive used to construct this BArchiver. May call archivable's Archive() method. More...
 
BMessageArchiveMessage () const
 Returns the BMessage* used to construct this BArchiver. This is the archive that AddArchivable() modifies. More...
 
status_t Finish (status_t err=B_OK)
 Report any archiving errors and possibly complete the archiving session. More...
 
status_t GetTokenForArchivable (BArchivable *archivable, int32 &_token)
 Equivalent to calling the expanded GetTokenForArchivable( BArchivable*, bool, int32&), with the deep parameter equal to true. More...
 
status_t GetTokenForArchivable (BArchivable *archivable, bool deep, int32 &_token)
 Get a token representing a BArchivable object for this archiving session. More...
 
bool IsArchived (BArchivable *archivable)
 Returns whether archivable has already been archived in this session. More...
 

Detailed Description

A class that simplifies the archiving of complicated BArchivable hierarchies.

The BArchiver class is a small class that is used for archiving of complicated BArchivable hierarchies. Such a hierarchy may include multiple BArchivable objects, each of which might be referenced by many BArchivable objects. With the BArchiver class, you can be certain that each BArchivable object is archived only once with very little work. When used in conjuction with the BArchivable::AllArchived() and BArchivable::AllUnarchived() methods, it is simple to rebuild your system of references upon unarchival so that they are equivalent to those that were present in your original hierarchy.

The objects you archive can be retrieved using a BUnarchiver object.

Since
Haiku R1

Constructor & Destructor Documentation

BArchiver::BArchiver ( BMessage archive)

Constructs a BArchiver object that manages archive.

Since
Haiku R1
BArchiver::~BArchiver ( )

Destroys a BArchiver object. If the BArchiver object has not had its Finish() method called, this will be done now.

Since
Haiku R1

Member Function Documentation

status_t BArchiver::AddArchivable ( const char *  name,
BArchivable archivable,
bool  deep = true 
)

Adds a reference to archivable to the archive used to construct this BArchiver. May call archivable's Archive() method.

Parameters
nameWhere this reference will be stored in the archive.
archivableThe BArchivable* object that to reference.
deepPassed to archivable->Archive() if archivable must be archived.

Adds a reference to archivable to your archive. If archivable has not yet been archived, then its Archive() method is called. BArchiver can only track BArchivable objects that have been archived through this method or the GetTokenForArchivable() methods.

Warning
If you manually archive an object, and then pass it to AddArchivable() or GetTokenForArchivable(), it will be archived again, and when unarchived you will end up with two different BArchivable objects.
Since
Haiku R1
const BMessage * BArchiver::ArchiveMessage ( ) const

Returns the BMessage* used to construct this BArchiver. This is the archive that AddArchivable() modifies.

Since
Haiku R1
status_t BArchiver::Finish ( status_t  err = B_OK)

Report any archiving errors and possibly complete the archiving session.

This method may finish an archiving session (triggering the call of all archived objects' AllArchived() methods) if the following conditions are true:

  • No errors have been reported to this or any other BArchiver object within this session.
  • This is the last remaining BArchiver that has not had its Finish() method invoked.

If you call this method with an error code not equal to B_OK, then this archiving session has failed, archived objects will not have their AllArchived() methods called, and any subsequent calls to this method on any BArchiver objects in this session will return your error code.

Returns
The first error reported in this archiving session, or B_OK.
Since
Haiku R1
status_t BArchiver::GetTokenForArchivable ( BArchivable archivable,
int32 &  _token 
)
inline

Equivalent to calling the expanded GetTokenForArchivable( BArchivable*, bool, int32&), with the deep parameter equal to true.

See also
GetTokenForArchivable(BArchivable*, bool, int32&)
Since
Haiku R1
status_t BArchiver::GetTokenForArchivable ( BArchivable archivable,
bool  deep,
int32 &  _token 
)

Get a token representing a BArchivable object for this archiving session.

Parameters
archivableThe BArchivable object for which you wish to get a token.
deepControls how archivable will be archived, if it has not yet been archived in this session.
[out]_tokenThe token representing archivable is stored here.

Retrieves or creates a token to represent archivable in this archiving session. If archivable has not yet been archived, it will be now. If archivable gets archived, the deep parameter will be passed to its Archive() method.

Warning
If you manually archive an object, and then pass it to GetTokenForArchivable(), it will be archived again, and when unarchived you will end up with two different BArchivable objects.
Since
Haiku R1
bool BArchiver::IsArchived ( BArchivable archivable)

Returns whether archivable has already been archived in this session.

Returns
Whether or not the object has already been archived.
Return values
truearchivable has been archived in this archiving session.
falsearchivable has not been archived in this archiving session.
Since
Haiku R1