i2p/haiku-beta6
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Technical proofreading by David Weizades.

Browse Source 
git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21264 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
2007-05-29 15:24:25 +00:00
parent e200a8e9b9
commit 37503f54ec
1 changed files with 109 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/support/Archivable.dox
+109 -108
View File
@@ -2,171 +2,172 @@
* Copyright 2007, Haiku, Inc. All Rights Reserved. * Copyright 2007, Haiku, Inc. All Rights Reserved.
* Distributed under the terms of the MIT License. * Distributed under the terms of the MIT License.
* *
* Documentation by: * Author:
* Niels Sascha Reedijk <[email protected]> * Niels Sascha Reedijk <[email protected]>
* Proofreader:
* David Weizades <[email protected]>
* Corresponds to: * Corresponds to:
* /trunk/headers/os/support/Archivable.h rev 19972 * /trunk/headers/os/support/Archivable.h rev 19972
* /trunk/src/kits/support/Archivable.cpp rev 19095 * /trunk/src/kits/support/Archivable.cpp rev 19095
*/ */
/*! /*!
\file Archivable.h \file Archivable.h
\brief Provides the BArchivable interface. \brief Provides the BArchivable interface.
*/ */
/*! /*!
\class BArchivable \class BArchivable
\ingroup support \ingroup support
\ingroup libbe \ingroup libbe
\brief Interfaced for objects that can be archived into a BMessage. \brief Interfaced for objects that can be archived into a BMessage.
BArchivable provides an interface for objects that can be archived into BArchivable provides an interface for objects that can be put into message
messages and unarchived to objects in another location. By these means you archives and extracted into objects in another location. Using this you are
are able to send objects between applications, or even between computers over able to send objects between applications, or even between computers across
networks. networks.
BArchivable differs from BFlattenable in way that BFlattenable is designed to BArchivable differs from BFlattenable in that BFlattenable is designed to
store objects to flat streams of data, where the main objective is storing it store objects into flat streams of data, the main objective being storage to
to disk. The objective of this interface is to archive objects that will be disk. The objective of this interface, however, is to store objects that will
restored as objects. To illustrate that point, BArchivable messages know how be restored to other objects. To illustrate this point, BArchivable messages
to restore itself, whereas BFlattenables have a datatype which you manually know how to restore themselves whereas BFlattenables have a datatype which
need to map to classes. you need to map to classes manually.
Archiving is done with the Archive() method. If your class support it, the Archiving is done with the Archive() method. If your class supports it, the
caller can request your class to to a deep archivation, which means that all caller can request it to store in to a deep archive, meaning that all child
child objects should be stored. Unarchiving works with the Instantiate() objects in it will be stored. Extracting the archive works with the
method, which is static. However, since the interface is designed to Instantiate() method, which is static. Since the interface is designed to
unarchive objects without the caller knowing what kind of object it extract objects without the caller knowing what kind of object it actually is
actually is, the global function #instantiate_object() instantiates a message the global function #instantiate_object() instantiates a message without you
without you manually having to determine the class the message is from. This manually having to determine the class the message is from. This adds
adds considerable flexibility and allows BArchivable to be used in considerable flexibility and allows BArchivable to be used in combination with
combination with add-ons. other add-ons.
To provide this interface in your classes, you should publicly inherit this To provide this interface in your classes you should publicly inherit this
class. You should reimplement Archive() and Instantiate(), and provide one class. You should implement Archive() and Instantiate(), and provide one
constructor that takes one BMessage argument. constructor that takes one BMessage argument.
*/ */
/*! /*!
\fn BArchivable::BArchivable(BMessage* from) \fn BArchivable::BArchivable(BMessage* from)
\brief Constructor. Does nothing. \brief Constructor. Does nothing.
If you inherit this interface, you should at least provide one constructor If you inherit this interface you should provide at least one constructor that
that takes one BMessage argument. takes one BMessage argument.
*/ */
/*! /*!
\fn BArchivable::BArchivable() \fn BArchivable::BArchivable()
\brief Constructor. Does nothing. \brief Constructor. Does nothing.
*/ */
/*! /*!
\fn BArchivable::~BArchivable() \fn BArchivable::~BArchivable()
\brief Destructor. Does nothing. \brief Destructor. Does nothing.
*/ */
/*! /*!
\fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const \fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const
\brief Archive the object into a BMessage. \brief Archive the object into a BMessage.
You should call this method from your derived implementation, as it finishes You should call this method from your derived implementation as it adds the
the message to contain data to instantiate your object. data needed to instantiate your object to the message.
\param into The message you may store your object in. \param into The message you store your object in.
\param deep If \c true, all child object of this object should be stored as \param deep If \c true, all children of this object should be stored as well.
well. Naturally, only pay attention of this parameter if you actually have Only pay attention of this parameter if you actually have child objects.
child objects.
\retval B_OK The archiving succeeded. \retval B_OK The archiving succeeded.
\retval "error codes" The archiving did not succeed. \retval "error codes" The archiving did not succeed.
*/ */
/*! /*!
\fn static BArchivable* BArchivable::Instantiate(BMessage* archive) \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
\brief Static member to restore objects from messages. \brief Static member to restore objects from messages.
You should always check that the \a archive argument actually corresponds to You should always check that the \a archive argument actually corresponds to
your class. The automatic functions, such as #instantiate_object() will not your class. The automatic functions, such as #instantiate_object() will not
choose the wrong class, but some manual calls to this member might be faulty. choose the wrong class but manual calls to this member might be faulty.
\param archive The message with the data to restore an object. \param archive The message with the data of the object to restore.
\retval You should return a pointer to your object, or \c NULL if you \retval You should return a pointer to your object, or \c NULL if you
failed to succeed. fail.
\warning The default implementation will always return \c NULL. Even though \warning The default implementation will always return \c NULL. Even though
it is possible to store plain BArchive objects, it is impossible to restore it is possible to store plain BArchive objects it is impossible to restore
them. them.
\see instantiate_object(BMessage *from) \see instantiate_object(BMessage *from)
*/ */
/*! /*!
\fn virtual status_t BArchivable::Perform(perform_code d, void* arg) \fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
\brief Internal method. \brief Internal method.
\internal This method is used to extend the API or to provide 'hidden' \internal This method is defined in case of unforseen binary compatbility API
features. Currently nothing of interest is implemented. issues. Currently nothing of interest in implemented.
*/ */
///////////////////// Global methods ///// Global methods /////
/*! /*!
\addtogroup support_globals \addtogroup support_globals
@{ @{
*/ */
/*! /*!
\typedef typedef BArchivable* (*instantiation_func)(BMessage*) \typedef typedef BArchivable* (*instantiation_func)(BMessage*)
\brief Internal definition of a function that can instantiate objects that \brief Internal definition of a function that can instantiate objects that
have been created with the BArchivable API. have been created with the BArchivable API.
*/ */
/*! /*!
\fn BArchivable* instantiate_object(BMessage *from, image_id *id) \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
\brief Instantiate an archived object with the object being defined in a \brief Instantiate an archived object with the object being defined in a
different application or library. different application or library.
This function is similar to instantiate_object(BMessage *from), except that This function is similar to instantiate_object(BMessage *from), except that
it takes the \a id argument that refers to an image where the object might it takes the \a id argument referring to an image where the object might
come from. stored.
\note Images are names for executable files. Image ids refer to these \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 executable files that have been loaded by your application. Have a look
at the kernel API. at the kernel API for further info.
*/ */
/*! /*!
\fn BArchivable* instantiate_object(BMessage *from) \fn BArchivable* instantiate_object(BMessage *from)
\brief Instantiate an archived object. \brief Instantiate an archived object.
This global function will determine the base class based on the \a from 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 argument, and it will call the Instantiate() function of that object to
restore it. restore it.
\param from The archived object. \param from The archived object.
\return The object returns a pointer to the instantiated object, or \c NULL \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 if the instantiation failed. The global \c errno variable will contain the
reason it failed. reason why it failed.
\see instantiate_object(BMessage *from, image_id *id) \see instantiate_object(BMessage *from, image_id *id)
*/ */
/*! /*!
\fn bool validate_instantiation(BMessage* from, const char* className) \fn bool validate_instantiation(BMessage* from, const char* className)
\brief Internal function that checks if the \a className is the same as the \brief Internal function that checks if the \a className is the same as the
one stored in the \a from message. one stored in the \a from message.
*/ */
/*! /*!
\fn instantiation_func find_instantiation_func(const char* className, const char* signature) \fn instantiation_func find_instantiation_func(const char* className, const char* signature)
\brief Internal function that searches for the instantiation func with a \brief Internal function that searches for the instantiation func with a
specific signature. Use instantiate_object() instead. specific signature. Use instantiate_object() instead.
*/ */
/*! /*!
\fn instantiation_func find_instantiation_func(const char* className) \fn instantiation_func find_instantiation_func(const char* className)
\brief Internal function that searches for the instantiation func of a \brief Internal function that searches for the instantiation func of a
specific class. Use instantiate_object() instead. specific class. Use instantiate_object() instead.
*/ */
/*! /*!
\fn instantiation_func find_instantiation_func(BMessage* archive) \fn instantiation_func find_instantiation_func(BMessage* archive)
\brief Internal function that searches for the instantiation func that \brief Internal function that searches for the instantiation func that
works on the specified \a archive. Use instantiate_object() instead. works on the specified \a archive. Use instantiate_object() instead.
*/ */
//! @} //! @}