mirror of
https://review.haiku-os.org/haiku
synced 2025-01-27 00:34:50 +01:00
a33f8fbdec
* Some new classes documented * Screenshots for the interface kit controls * A lot of typo fixes * Some css tweaks This has some backporting to the current version of Doxygen, since there are experiments to get coloring similar to the one in the Be Book that will hopefully be upstreamed in Doxygen. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@42608 a95241bf-73f2-0310-859d-f6bbb57e9c96
238 lines
8.6 KiB
Plaintext
238 lines
8.6 KiB
Plaintext
/*
|
|
* Copyright 2007, Haiku, Inc. All Rights Reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Niels Sascha Reedijk, niels.reedijk@gmail.com
|
|
* Alex Wilson, yourpalal2@gmail.com
|
|
*
|
|
* Proofreader:
|
|
* David Weizades, ddewbofh@hotmail.com
|
|
* Thom Holwerda, slakje@quicknet.nl
|
|
*
|
|
* Corresponds to:
|
|
* /trunk/headers/os/support/Archivable.h rev 37751
|
|
* /trunk/src/kits/support/Archivable.cpp rev 37751
|
|
*/
|
|
|
|
|
|
/*! \file Archivable.h
|
|
\brief Provides the BArchivable interface and declares the BArchiver and
|
|
BUnarchiver classes.
|
|
*/
|
|
|
|
|
|
/*! \class BArchivable
|
|
\ingroup support
|
|
\ingroup libbe
|
|
\brief Interface for objects that can be archived into a BMessage.
|
|
|
|
BArchivable provides an interface for objects that can be put into message
|
|
archives and extracted into objects in another location. Using this you are
|
|
able to send objects between applications, or even between computers across
|
|
networks.
|
|
|
|
BArchivable differs from BFlattenable in that BFlattenable is designed to
|
|
store objects into flat streams of data, the main objective being storage to
|
|
disk. The objective of this interface, however, is to store objects that
|
|
will later be restored as new (but identical) objects. To illustrate this
|
|
point, BArchivable objects can be restored automatically to the correct
|
|
class, whereas BFlattenables have a data type which you need to map to
|
|
classes manually.
|
|
|
|
Archiving is done with the Archive() method. If your class supports it, the
|
|
caller can request it to store into a deep archive, meaning that all child
|
|
objects in it will be stored. Extracting the archive works with the
|
|
Instantiate() method, which is static. Since the interface is designed to
|
|
extract objects without the caller knowing what kind of object it actually
|
|
is, the global function #instantiate_object() instantiates a message without
|
|
you manually having to determine the class the message is from. This adds
|
|
considerable flexibility and allows BArchivable to be used in combination
|
|
with other add-ons.
|
|
|
|
To provide this interface in your classes you should publicly inherit this
|
|
class. You should implement Archive() and Instantiate(), and provide one
|
|
constructor that takes one BMessage argument.
|
|
|
|
If your class holds references to other BArchivable objects that you wish
|
|
to archive, then you should consider using the BArchiver and BUnarchiver
|
|
classes in your Archive() method and archive constructor, respectively.
|
|
You should also consider implementing the AllArchived() and AllUnarchived()
|
|
methods, which were designed to ease archiving and unarchiving in such
|
|
a situation.
|
|
*/
|
|
|
|
|
|
/*! \fn BArchivable::BArchivable(BMessage* from)
|
|
\brief Constructor. Does important behind-the-scenes work in the unarchiving
|
|
process.
|
|
|
|
If you inherit this interface you should provide at least one constructor
|
|
that takes one BMessage argument. In that constructor, you should call your
|
|
parent class' archive constructor (even if your parent class is
|
|
BArchivable).
|
|
*/
|
|
|
|
|
|
/*! \fn BArchivable::BArchivable()
|
|
\brief Constructor. Does nothing.
|
|
*/
|
|
|
|
|
|
/*! \fn BArchivable::~BArchivable()
|
|
\brief Destructor. Does nothing.
|
|
*/
|
|
|
|
|
|
/*! \fn virtual status_t BArchivable::Archive(BMessage* into,
|
|
bool deep = true) const
|
|
\brief Archive the object into a BMessage.
|
|
|
|
You should call this method from your derived implementation as it adds the
|
|
data needed to instantiate your object to the message.
|
|
|
|
\param into The message you store your object in.
|
|
\param deep If \c true, all children of this object should be archived as
|
|
well.
|
|
\retval B_OK The archiving succeeded.
|
|
\retval "error codes" The archiving did not succeed.
|
|
*/
|
|
|
|
|
|
/*! \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
|
|
\brief Static member to restore objects from messages.
|
|
|
|
You should always check that the \a archive argument actually corresponds to
|
|
your class. The automatic functions, such as #instantiate_object() and
|
|
BUnarchiver::InstantiateObject() will not choose the wrong class but manual
|
|
calls to this member might be faulty. You can verify that \c archive
|
|
stores an object of your calss with the validate_instantiation() function.
|
|
|
|
\param archive The message with the data of the object to restore.
|
|
\retval You should return a pointer to the object you create with
|
|
\c archive, or \c NULL if unarchival fails.
|
|
\warning The default implementation will always return \c NULL. Even though
|
|
it is possible to store plain BArchivable objects, it is impossible to
|
|
restore them.
|
|
|
|
\see instantiate_object(BMessage *from)
|
|
\see BUnarchiver::InstantiateObject()
|
|
*/
|
|
|
|
|
|
/*! \fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
|
|
\brief Internal method defined for binary compatibility purposes.
|
|
\internal This method is defined for binary compatibility purposes, it is
|
|
used to ensure that the correct AllUnarchived() and AllArchived()
|
|
methods are called for objects, as those methods are new to Haiku.
|
|
*/
|
|
|
|
|
|
/*! \fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive)
|
|
\brief Method relating to the use of \c BUnarchiver.
|
|
|
|
This hook function is called triggered in the BUnarchiver::Finish() method.
|
|
In this method, you can rebuild references to objects that may be direct
|
|
children of your object, or may be children of other objects.
|
|
Implementations of this method should call the implementation of
|
|
their parent class, the same as for the Archive() method.
|
|
|
|
\warning To guarantee that your AllUnarchived() method will be called
|
|
during unarchival, you must create a BUnarchiver object in your
|
|
archive constructor.
|
|
|
|
\see BUnarchiver, BUnarchiver::Finish()
|
|
*/
|
|
|
|
|
|
/*! \fn virtual status_t BArchivable::AllArchived(BMessage* into) const
|
|
\brief Method relating to the use of \c BArchiver.
|
|
|
|
This hook function is called once the first BArchiver that was created in
|
|
an archiving session is either destroyed, or has its Finish() method
|
|
called. Implementations of this method can be used, in conjunction with
|
|
BArchiver::IsArchived(), to reference objects in your archive that you
|
|
do not own, depending on whether or not those objects were archived by their
|
|
owners. Implementations of this method should call the implementation of
|
|
their parent class, the same as for the Archive() method.
|
|
|
|
\warning To guarantee that your AllArchived() method will be called
|
|
during archival, you must create a BArchiver object in your
|
|
Archive() implementation.
|
|
|
|
\warning You should archive any objects you own in your Archive()
|
|
method implementation, and \b NOT your AllArchived() method.
|
|
|
|
\see BArchiver BArchiver::Finish()
|
|
*/
|
|
|
|
|
|
///// Global methods /////
|
|
/*!
|
|
\addtogroup support_globals
|
|
@{
|
|
*/
|
|
|
|
|
|
/*! \typedef typedef BArchivable* (*instantiation_func)(BMessage*)
|
|
\brief Internal definition of a function that can instantiate objects that
|
|
have been created with the BArchivable API.
|
|
*/
|
|
|
|
|
|
/*! \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
|
|
\brief Instantiate an archived object with the object being defined in a
|
|
different application or library.
|
|
|
|
This function is similar to instantiate_object(BMessage *from), except that
|
|
it takes the \a id argument referring to an image where the object might be
|
|
stored.
|
|
|
|
\note Images are names for executable files. Image id's refer to these
|
|
executable files that have been loaded by your application. Have a look
|
|
at the kernel API for further information.
|
|
*/
|
|
|
|
|
|
/*! \fn BArchivable* instantiate_object(BMessage *from)
|
|
\brief Instantiate an archived object.
|
|
|
|
This global function will determine the base class, based on the \a from
|
|
argument, and it will call the Instantiate() function of that object to
|
|
restore it.
|
|
|
|
\param from The archived object.
|
|
\return The object returns a pointer to the instantiated object, or \c NULL
|
|
if the instantiation failed. The global \c errno variable will contain
|
|
the reason why it failed.
|
|
\see instantiate_object(BMessage *from, image_id *id)
|
|
*/
|
|
|
|
|
|
/*! \fn bool validate_instantiation(BMessage* from, const char* className)
|
|
\brief Internal function that checks if the \a className is the same as the
|
|
one stored in the \a from message.
|
|
*/
|
|
|
|
|
|
/*! \fn instantiation_func find_instantiation_func(const char* className,
|
|
const char* signature)
|
|
\brief Internal function that searches for the instantiation func with a
|
|
specific signature. Use instantiate_object() instead.
|
|
*/
|
|
|
|
|
|
/*! \fn instantiation_func find_instantiation_func(const char* className)
|
|
\brief Internal function that searches for the instantiation func of a
|
|
specific class. Use instantiate_object() instead.
|
|
*/
|
|
|
|
|
|
/*! \fn instantiation_func find_instantiation_func(BMessage* archive)
|
|
\brief Internal function that searches for the instantiation func that
|
|
works on the specified \a archive. Use instantiate_object() instead.
|
|
*/
|
|
|
|
|
|
//! @}
|