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

Public Types
enum	ownership_policy { B_ASSUME_OWNERSHIP , B_DONT_ASSUME_OWNERSHIP }
	Options for the ownership policy of objects retrieved from BUnarchiver. More...

Public Member Functions
	BUnarchiver (const BMessage *archive)
	Constructs a BUnarchiver object to manage `archive`.

	~BUnarchiver ()
	Destroys a BUnarchiver object.

const BMessage *	ArchiveMessage () const
	Returns the BMessage* used to construct this BUnarchiver.

void	AssumeOwnership (BArchivable *archivable)
	Become the owner of archivable.

status_t	EnsureUnarchived (const char *name, int32 index=0)
	Ensure the object archived under name at index is unarchived and instantiated.

status_t	EnsureUnarchived (int32 token)
	Ensure the object represented by token is unarchived and instantiated.

template<class T >
status_t	FindObject (const char name, int32 index, ownership_policy owning, T &object)
	Recover an object that had previously been archived using the BArchiver::AddArchivable() method.

template<class T >
status_t	FindObject (const char name, int32 index, T &object)
	Recover and take ownership of an object that had previously been archived using the BArchiver::AddArchivable() method.

template<class T >
status_t	FindObject (const char name, ownership_policy owning, T &object)
	Recover an object at index `0` that had previously been archived using the BArchiver::AddArchivable() method.

template<class T >
status_t	FindObject (const char name, T &object)
	Recover and take ownership of an object at index `0` that had previously been archived using the BArchiver::AddArchivable() method.

status_t	Finish (status_t err=B_OK)
	Report any unarchiving errors and possibly complete the archiving session.

template<class T >
status_t	GetObject (int32 token, ownership_policy owning, T *&object)
	Recover an object by token that was archived by a BArchiver object. If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be instantiated now.

template<class T >
status_t	GetObject (int32 token, T *&object)
	Recover and take ownership of an object represented by token.

bool	IsInstantiated (const char *name, int32 index=0)
	Checks whether the object archived under name at index has been instantiated in this session.

bool	IsInstantiated (int32 token)
	Checks whether the object represented by `token` has been instantiated in this session.

void	RelinquishOwnership (BArchivable *archivable)
	Relinquish ownership of archivable. If archivable remains unclaimed at the end of the unarchiving session, it will be deleted (unless it is the root object).

Static Public Member Functions
template<class T >
static status_t	InstantiateObject (BMessage archive, T &object)
	Attempt to instantiate an object of type T from BMessage* from.

static bool	IsArchiveManaged (const BMessage *archive)
	Checks whether archive was managed by a BArchiver object.

static BMessage *	PrepareArchive (BMessage *&archive)
	Prepares `archive` for use by a BUnarchiver.

Detailed Description

A class that simplifies the unarchiving of complicated BArchivable hierarchies.

The BUnarchiver class is a small class used to recover BArchivable objects that have been archived with the BArchiver class. It also provides ownership semantics, so that memory leaks can be avoided during the unarchival process. When retrieving an object (either via GetObject() or FindObject()), you can specify a BUnarchiver::ownership_policy. If you specify BUnarchiver::B_ASSUME_OWNERSHIP, you will become responsible for deleting the retrieved item. If you specify BUnarchiver::B_DONT_ASSUME_OWNERSHIP, you will not become responsible. You cannot take ownership of the same object twice. After the unarchival process finishes, any unclaimed objects, excluding the root object (the object being instantiated via instantiate_object() or BUnarchiver::InstantiateObject()), will be deleted.

If you are updating a class that previously did not use the BArchiver and BUnarchiver helper classes, and want to maintain backwards compatibility with old archive, this can be done using the IsArchiveManaged() method.

Warning: Calling methods on your BUnarchiver with a legacy archive (one that was not managed by a BArchiver during archival) will result in a call to debugger().

Since: Haiku R1

Member Enumeration Documentation

◆ ownership_policy

enum BUnarchiver::ownership_policy

Options for the ownership policy of objects retrieved from BUnarchiver.

Since: Haiku R1

Enumerator

B_ASSUME_OWNERSHIP

Ownership of unarchived objects will be transferred to the caller.

Since: Haiku R1

B_DONT_ASSUME_OWNERSHIP

The unarchived objects will be borrowed to the caller.

Since: Haiku R1

Constructor & Destructor Documentation

◆ BUnarchiver()

BUnarchiver::BUnarchiver ( const BMessage * archive )

Constructs a BUnarchiver object to manage archive.

Note: To guarantee that your AllUnarchived() method will be called during archival, you must create a BUnarchiver object in your archive constructor. It is necessary to do this even if you won't use the BUnarchiver object in your archive constructor.

Warning: Do not construct a BUnarchiver object without first calling BUnarchiver::PrepareArchive() on archive. It is only safe to build a BUnarchiver without this call in your AllUnarchived() implementation.

See also: BUnarchiver::PrepareArchive()

Since: Haiku R1

◆ ~BUnarchiver()

BUnarchiver::~BUnarchiver ( )

Destroys a BUnarchiver object.

Calls this objects Finish() method, if it has not yet been called.

Since: Haiku R1

Member Function Documentation

◆ ArchiveMessage()

const BMessage * BUnarchiver::ArchiveMessage ( ) const

Returns the BMessage* used to construct this BUnarchiver.

This is the archive that FindObject() uses.

◆ AssumeOwnership()

void BUnarchiver::AssumeOwnership ( BArchivable * archivable )

Become the owner of archivable.

After calling this method you are responsible for deleting the archivable.

Parameters

archivable The archivable object.

Since: Haiku R1

◆ EnsureUnarchived() [1/2]

status_t BUnarchiver::EnsureUnarchived	(	const char *	name,
		int32	index = `0`
	)

inline

Ensure the object archived under name at index is unarchived and instantiated.

Parameters

name	The archive name.
index	The archive index.

Returns: A status code.

Since: Haiku R1

References B_DONT_ASSUME_OWNERSHIP, and FindObject().

◆ EnsureUnarchived() [2/2]

status_t BUnarchiver::EnsureUnarchived ( int32 token )

inline

Ensure the object represented by token is unarchived and instantiated.

Parameters

token the object token

Returns: A status code.

Since: Haiku R1

References B_DONT_ASSUME_OWNERSHIP, and GetObject().

◆ FindObject() [1/4]

template<class T >

status_t BUnarchiver::FindObject	(	const char *	name,
		int32	index,
		ownership_policy	owning,
		T *&	object
	)

Recover an object that had previously been archived using the BArchiver::AddArchivable() method.

If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be instantiated now.

If the retrieved object is not of the type T, then this method will fail. If this method fails, you will not receive ownership of the object, no matter what you specified in owning.

Template Parameters

T	The type of object you wish to find.

Parameters

name	The name that was passed to BArchiver::AddArchivable() when adding this object.
index	The index of the object you wish to recover (`0-based`, like BMessage::FindData().
owning	Dictates whether or not you wish to take ownership of the retrieved object.
object	Return parameter for the retrieved object of type T.

Returns: A status code.

Return values

B_OK	The object retrieved was of type T.
B_BAD_TYPE	The object retrieved was not of type T.

Since: Haiku R1

References B_ASSUME_OWNERSHIP, FindObject(), NULL, and RelinquishOwnership().

◆ FindObject() [2/4]

template<class T >

status_t BUnarchiver::FindObject	(	const char *	name,
		int32	index,
		T *&	object
	)

inline

Recover and take ownership of an object that had previously been archived using the BArchiver::AddArchivable() method.

Template Parameters

T	The type of object you wish to find.

Parameters

name	The name that was passed to BArchiver::AddArchivable() when adding this object.
index	The index of the object you wish to recover (`0-based`, like BMessage::FindData().
object	Return parameter for the retrieved object of type T.

Returns: A status code.

Return values

B_OK	The object retrieved was of type T.
B_BAD_TYPE	The object retrieved was not of type T.

Since: Haiku R1

References B_ASSUME_OWNERSHIP, and FindObject().

◆ FindObject() [3/4]

template<class T >

status_t BUnarchiver::FindObject	(	const char *	name,
		ownership_policy	owning,
		T *&	object
	)

inline

Recover an object at index 0 that had previously been archived using the BArchiver::AddArchivable() method.

Equivalent to calling FindObject(name, 0, owning, object).

Template Parameters

T	The type of object you wish to find.

Parameters

name	The name that was passed to BArchiver::AddArchivable() when adding this object.
owning	Dictates whether or not you wish to take ownership of the retrieved object.
object	Return parameter for the retrieved object of type T.

Returns: A status code.

Return values

B_OK	The object retrieved was of type T.
B_BAD_TYPE	The object retrieved was not of type T.

Since: Haiku R1

References FindObject().

◆ FindObject() [4/4]

template<class T >

status_t BUnarchiver::FindObject	(	const char *	name,
		T *&	object
	)

inline

Recover and take ownership of an object at index 0 that had previously been archived using the BArchiver::AddArchivable() method.

Equivalent to calling FindObject(name, 0, BUnarchiver::B_ASSUME_OWNERSHIP, object).

Template Parameters

T	The type of object you wish to find.

Parameters

name	The name that was passed to BArchiver::AddArchivable() when adding this object.
object	Return parameter for the retrieved object of type T.

Returns: A status code.

Return values

B_OK	The object retrieved was of type T.
B_BAD_TYPE	The object retrieved was not of type T.

Since: Haiku R1

References B_ASSUME_OWNERSHIP.

Referenced by EnsureUnarchived(), and FindObject().

◆ Finish()

status_t BUnarchiver::Finish ( status_t err = B_OK )

Report any unarchiving errors and possibly complete the archiving session.

This method may finish an unarchiving session (triggering the call of all instantiated objects' AllUnarchived() methods) if the following conditions are true:

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

If you call this method with an error code not equal to B_OK, then this unarchiving session has failed, instantiated objects will not have their AllUnarchived() methods called, and any subsequent calls to this method on any BUnarchiver objects in this session will return your error code. Furthermore, any objects that have been instantiated, but have not had their ownership assumed by another object will now be deleted (excluding the root object).

Returns: The first error reported in this unarchiving session, or B_OK.

Since: Haiku R1

◆ GetObject() [1/2]

template<class T >

status_t BUnarchiver::GetObject	(	int32	token,
		ownership_policy	owning,
		T *&	object
	)

Recover an object by token that was archived by a BArchiver object. If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be instantiated now.

If the retrieved object is not of the type T, then this method will fail. If this method fails, you will not receive ownership of the object, no matter what you specified in owning.

Template Parameters

T	The type of object you wish to find.

Parameters

token	The token you got for this object from BArchiver::GetTokenForArchivable() during archival.
owning	Whether or not you wish to take ownership of the retrieved object.
object	Return parameter for the retrieved object of type T.

Returns: A status code.

Return values

B_OK	The object retrieved was of type T.
B_BAD_TYPE	The object retrieved was not of type T.

Since: Haiku R1

References B_ASSUME_OWNERSHIP, GetObject(), NULL, and RelinquishOwnership().

◆ GetObject() [2/2]

template<class T >

status_t BUnarchiver::GetObject	(	int32	token,
		T *&	object
	)

inline

Recover and take ownership of an object represented by token.

Equivalent to calling GetObject(token, B_ASSUME_OWNERSHIP, object)

Template Parameters

T	The type of object you wish to find.

Parameters

token	The token you got for this object from BArchiver::GetTokenForArchivable() during archival.
object	The return parameter for the retrieved object of type T.

Returns: A status code.

Return values

B_OK	The object retrieved was of type T.
B_BAD_TYPE	The object retrieved was not of type T.

Since: Haiku R1

References B_ASSUME_OWNERSHIP.

Referenced by EnsureUnarchived(), and GetObject().

◆ InstantiateObject()

template<class T >

status_t BUnarchiver::InstantiateObject	(	BMessage *	from,
		T *&	object
	)

static

Attempt to instantiate an object of type T from BMessage* from.

If the instantiated object is not of type T, then it will be deleted, and this method will return B_BAD_TYPE. This method is similar to the instantiate_object() function, but provides error reporting and protection from memory leaks.

Parameters

from	The BMessage to instantiate from.
object	Return parameter for the retrieved object of type T.

Returns: A status code.

Return values

B_OK	The object retrieved was of type T.
B_BAD_TYPE	The object retrieved was not of type T.

Since: Haiku R1

References InstantiateObject(), and NULL.

Referenced by InstantiateObject().

◆ IsArchiveManaged()

static bool BUnarchiver::IsArchiveManaged ( const BMessage * archive )

static

Checks whether archive was managed by a BArchiver object.

This method can be used to maintain archive backwards-compatibility for a class that has been updated to use the BArchiver class. If there is a possibility that you are may dealing with a legacy archive, you can use this method to find out before calling any methods on your BUnarchiver object.

Here is an example of how you might use this method. Note that you must still call PrepareArchive(archive) either way.

MyArchivableClas::MyArchivableClass(BMessage* archive)
    :
    BArchivable(BUnarchiver::PrepareArchive(archive))
{
    BUnarchiver unarchiver(archive);
 
    if (BUnarchiver::IsArchiveManaged(archive)) {
        // ... calls to FindObject() or GetObject() here ...
    } else {
        // ... calls to BMessage::FindMessage() here ...
    }
}

Returns: Whether archive was managed by a BArchiver object.

Return values

true	if archive was managed by a BArchiver object.
false	otherwise.

Since: Haiku R1

◆ IsInstantiated() [1/2]

bool BUnarchiver::IsInstantiated	(	const char *	name,
		int32	index = `0`
	)

Checks whether the object archived under name at index has been instantiated in this session.

Parameters

name	The archive name.
index	The arcive token.

Returns: true if instantiated, false otherwise.

Since: Haiku R1

◆ IsInstantiated() [2/2]

bool BUnarchiver::IsInstantiated ( int32 token )

Checks whether the object represented by token has been instantiated in this session.

Parameters

token The object token.

Returns: true if instantiated, false otherwise

Since: Haiku R1

◆ PrepareArchive()

static BMessage * BUnarchiver::PrepareArchive ( BMessage *& archive )

static

Prepares archive for use by a BUnarchiver.

This method must be called if you plan to use a BUnarchiver on an archive. It must be called once for each class an object inherits from that will use a BUnarchiver.

Warning: This method must be called before a call to the archive constructor of your parent class.

Notice the use of this method in the example provided below.

MyArchivableClas::MyArchivableClas(BMessage* archive)
    :
    BArchivable(BUnarchiver::PrepareArchive(archive))
{
    // ...
}

Parameters

archive The archive you wish to have prepared.

Returns: The same BMessage as is passed in.

Since: Haiku R1

◆ RelinquishOwnership()

void BUnarchiver::RelinquishOwnership ( BArchivable * archivable )

Relinquish ownership of archivable. If archivable remains unclaimed at the end of the unarchiving session, it will be deleted (unless it is the root object).

Parameters

archivable The archivable object.

Since: Haiku R1

Referenced by FindObject(), and GetObject().

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ ownership_policy

Constructor & Destructor Documentation

◆ BUnarchiver()

◆ ~BUnarchiver()

Member Function Documentation

◆ ArchiveMessage()

◆ AssumeOwnership()

◆ EnsureUnarchived() [1/2]

◆ EnsureUnarchived() [2/2]

◆ FindObject() [1/4]

◆ FindObject() [2/4]

◆ FindObject() [3/4]

◆ FindObject() [4/4]

◆ Finish()

◆ GetObject() [1/2]

◆ GetObject() [2/2]

◆ InstantiateObject()

◆ IsArchiveManaged()

◆ IsInstantiated() [1/2]

◆ IsInstantiated() [2/2]

◆ PrepareArchive()

◆ RelinquishOwnership()