All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Types | Public Member Functions | Static Public Member Functions | List of all members
BUnarchiver Class Reference

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 BMessageArchiveMessage () 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 BMessagePrepareArchive (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

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
archivableThe 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
nameThe archive name.
indexThe 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
tokenthe 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
TThe type of object you wish to find.
Parameters
nameThe name that was passed to BArchiver::AddArchivable() when adding this object.
indexThe index of the object you wish to recover (0-based, like BMessage::FindData().
owningDictates whether or not you wish to take ownership of the retrieved object.
objectReturn parameter for the retrieved object of type T.
Returns
A status code.
Return values
B_OKThe object retrieved was of type T.
B_BAD_TYPEThe 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
TThe type of object you wish to find.
Parameters
nameThe name that was passed to BArchiver::AddArchivable() when adding this object.
indexThe index of the object you wish to recover (0-based, like BMessage::FindData().
objectReturn parameter for the retrieved object of type T.
Returns
A status code.
Return values
B_OKThe object retrieved was of type T.
B_BAD_TYPEThe 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
TThe type of object you wish to find.
Parameters
nameThe name that was passed to BArchiver::AddArchivable() when adding this object.
owningDictates whether or not you wish to take ownership of the retrieved object.
objectReturn parameter for the retrieved object of type T.
Returns
A status code.
Return values
B_OKThe object retrieved was of type T.
B_BAD_TYPEThe 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
TThe type of object you wish to find.
Parameters
nameThe name that was passed to BArchiver::AddArchivable() when adding this object.
objectReturn parameter for the retrieved object of type T.
Returns
A status code.
Return values
B_OKThe object retrieved was of type T.
B_BAD_TYPEThe 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
TThe type of object you wish to find.
Parameters
tokenThe token you got for this object from BArchiver::GetTokenForArchivable() during archival.
owningWhether or not you wish to take ownership of the retrieved object.
objectReturn parameter for the retrieved object of type T.
Returns
A status code.
Return values
B_OKThe object retrieved was of type T.
B_BAD_TYPEThe 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
TThe type of object you wish to find.
Parameters
tokenThe token you got for this object from BArchiver::GetTokenForArchivable() during archival.
objectThe return parameter for the retrieved object of type T.
Returns
A status code.
Return values
B_OKThe object retrieved was of type T.
B_BAD_TYPEThe 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
fromThe BMessage to instantiate from.
objectReturn parameter for the retrieved object of type T.
Returns
A status code.
Return values
B_OKThe object retrieved was of type T.
B_BAD_TYPEThe 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)
:
{
BUnarchiver unarchiver(archive);
// ... calls to FindObject() or GetObject() here ...
} else {
// ... calls to BMessage::FindMessage() here ...
}
}
Interface for objects that can be archived into a BMessage.
Definition: Archivable.h:28
A container that can be send and received using the Haiku messaging subsystem.
Definition: Message.h:56
A class that simplifies the unarchiving of complicated BArchivable hierarchies.
Definition: Archivable.h:85
static BMessage * PrepareArchive(BMessage *&archive)
Prepares archive for use by a BUnarchiver.
static bool IsArchiveManaged(const BMessage *archive)
Checks whether archive was managed by a BArchiver object.
Returns
Whether archive was managed by a BArchiver object.
Return values
trueif archive was managed by a BArchiver object.
falseotherwise.
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
nameThe archive name.
indexThe 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
tokenThe 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)
:
{
// ...
}
Parameters
archiveThe 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
archivableThe archivable object.
Since
Haiku R1

Referenced by FindObject(), and GetObject().