BArchiver Class Reference

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

List of all members.

Public Member Functions
	BArchiver (BMessage *archive)
	Constructs a BArchiver object that manages archive.
	~BArchiver ()
	Destroys a BArchiver object. If the BArchiver object has not had its Finish() method called, this will be done now.
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.
BMessage *	ArchiveMessage () const
	Returns the BMessage* used to construct this BArchiver. This is the archive that AddArchivable() modifies.
status_t	Finish (status_t err=B_OK)
	Report any archiving errors and possibly complete the archiving session.
status_t	GetTokenForArchivable (BArchivable *archivable, int32 &_token)
	Equivalent to calling the expanded GetTokenForArchivable( BArchivable*, bool, int32&), with the deep parameter equal to true.
status_t	GetTokenForArchivable (BArchivable *archivable, bool deep, int32 &_token)
	Get a token representing a BArchivable object for this archiving session.
bool	IsArchived (BArchivable *archivable)
	Returns whether archivable has already been archived in this session.

---

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.

---

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:

name	Where this reference will be stored in the archive.
archivable	The BArchivable* object that to reference.
deep	Passed 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.

status_t BArchiver::Finish

(

status_t

err = B_OK

)

Report any archiving errors and possibly complete the archiving session.

Returns:

The first error reported in this archiving session, or B_OK.

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.

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&)

status_t BArchiver::GetTokenForArchivable	(	BArchivable *	archivable,
		bool	deep,
		int32 &	_token
	)

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

Parameters:

	archivable	The BArchivable object for which you wish to get a token.
	deep	Controls how archivable will be archived, if it has not yet been archived in this session.
[out]	_token	The 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.

bool BArchiver::IsArchived

(

BArchivable *

archivable

)

Returns whether archivable has already been archived in this session.

Return values:

true	archivable has been archived in this archiving session.
false	archivable has not been archived in this archiving session.