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

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, bool deep, int32 &_token)
	Get a token representing a BArchivable object for this 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`.

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.

Since: Haiku R1

Constructor & Destructor Documentation

◆ BArchiver()

BArchiver::BArchiver ( BMessage * archive )

Constructs a BArchiver object that manages archive.

Since: Haiku R1

◆ ~BArchiver()

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

◆ AddArchivable()

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.

Since: Haiku R1

◆ ArchiveMessage()

const BMessage * BArchiver::ArchiveMessage ( ) const

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

Since: Haiku R1

◆ Finish()

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

◆ GetTokenForArchivable() [1/2]

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.

Since: Haiku R1

◆ GetTokenForArchivable() [2/2]

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

References GetTokenForArchivable().

Referenced by GetTokenForArchivable().

◆ IsArchived()

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

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

Since: Haiku R1

Public Member Functions