haiku/docs/user/support/Archiver.dox

139 lines
4.7 KiB
Plaintext
Raw Normal View History

/*
* Copyright 2010, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License.
*
* Author:
* Alex Wilson, yourpalal2@gmail.com
*
* Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 37751
* /trunk/src/kits/support/Archivable.cpp rev 37751
*/
/*!
\class BArchiver
\ingroup support
\ingroup libbe
\brief 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.
*/
/*!
\fn BArchiver::BArchiver(BMessage* archive)
\brief Constructs a BArchiver object that manages \c archive.
*/
/*!
\fn BArchiver::~BArchiver()
\brief Destroys a BArchiver object. If the BArchiver object has not had its
Finish() method called, this will be done now.
*/
/*!
\fn status_t BArchiver::AddArchivable(const char* name,
BArchivable* archivable, bool deep = true)
\brief Adds a reference to \c archivable to the archive used to
construct this BArchiver. May call \c archivable's Archive() method.
\param name Where this reference will be stored in the archive.
\param archivable The BArchivable* object that to reference.
\param deep Passed to \c archivable->Archive() if \c archivable must
be archived.
Adds a reference to \c archivable to your archive. If \c 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.
*/
/*!
\fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable,
bool deep, int32& _token);
\brief Get a token representing \c archivable for this archiving
session.
\param deep Controls how \c archivable will be archived, if it has not yet
been archived in this session.
\param[out] _token The token representing \c archivable is stored here.
Retrieves or creates a token to represent \c archivable in this archiving
session. If \c archivable has not yet been archived, it will be now. If
\c archivable gets archived, the \c 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.
*/
/*!
\fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable,
int32 &_token)
\brief Equivalent to calling the expanded GetTokenForArchivable(
BArchivable*, bool, int32&), with the deep parameter equal to true.
\see GetTokenForArchivable(BArchivable*, bool, int32&)
*/
/*!
\fn bool BArchiver::IsArchived(BArchivable* archivable);
\brief Returns whether \c archivable has already been archived in this
session.
\retval true \c archivable has been archived in this archiving session.
\retval false \c archivable has not been archived in this archiving session.
*/
/*!
\fn status_t BArchiver::Finish(status_t err = B_OK);
\brief Report any archiving errors and possibly complete the archiving
session.
\return 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:
\li No errors have been reported to this or any other BArchiver object
within this session.
\li 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.
*/
/*!
\fn const BMessage* BArchiver::ArchiveMessage() const
\brief Returns the BMessage* used to construct this BArchiver. This is
the archive that AddArchivable() modifies.
*/