docs/user/support/Archivable.dox

   1 /*
   2  * Copyright 2007 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   7  *              Alex Wilson, yourpalal2@gmail.com
   8  *              John Scipione, jscipione@gmail.com
   9  *
  10  * Proofreader:
  11  *              David Weizades, ddewbofh@hotmail.com
  12  *              Thom Holwerda, slakje@quicknet.nl
  13  *
  14  * Corresponds to:
  15  *              headers/os/support/Archivable.h rev 37751
  16  *              src/kits/support/Archivable.cpp rev 44303
  17  */
  18
  19
  20 /*!
  21         \file Archivable.h
  22         \ingroup support
  23         \ingroup libbe
  24         \brief Provides the BArchivable interface and declares the BArchiver and
  25                BUnarchiver classes.
  26 */
  27
  28
  29 /*!
  30         \class BArchivable
  31         \ingroup support
  32         \ingroup libbe
  33         \brief Interface for objects that can be archived into a BMessage.
  34
  35         BArchivable provides an interface for objects that can be put into message
  36         archives and extracted into objects in another location. Using this you are
  37         able to send objects between applications, or even between computers across
  38         networks.
  39
  40         BArchivable differs from BFlattenable in that BFlattenable is designed to
  41         store objects into flat streams of data, the main objective being storage to
  42         disk. The objective of this interface, however, is to store objects that
  43         will later be restored as new (but identical) objects. To illustrate this
  44         point, BArchivable objects can be restored automatically to the correct
  45         class, whereas BFlattenable objects have a data type which you need to map
  46         to classes manually.
  47
  48         Archiving is done with the Archive() method. If your class supports it, the
  49         caller can request it to store into a deep archive, meaning that all child
  50         objects in it will be stored. Extracting the archive works with the
  51         Instantiate() method, which is static. Since the interface is designed to
  52         extract objects without the caller knowing what kind of object it actually
  53         is, the global function #instantiate_object() instantiates a message without
  54         you manually having to determine the class the message is from. This adds
  55         considerable flexibility and allows BArchivable to be used in combination
  56         with other add-ons.
  57
  58         To provide this interface in your classes you should publicly inherit this
  59         class. You should implement Archive() and Instantiate(), and provide one
  60         constructor that takes one BMessage argument.
  61
  62         If your class holds references to other BArchivable objects that you wish
  63         to archive, then you should consider using the BArchiver and BUnarchiver
  64         classes in your Archive() method and archive constructor, respectively.
  65         You should also consider implementing the AllArchived() and AllUnarchived()
  66         methods, which were designed to ease archiving and unarchiving in such
  67         a situation.
  68
  69         \since BeOS R3
  70 */
  71
  72
  73 /*!
  74         \fn BArchivable::BArchivable(BMessage* from)
  75         \brief Constructor. Does important behind-the-scenes work in the
  76                    unarchiving process.
  77
  78         If you inherit this interface you should provide at least one constructor
  79         that takes one BMessage argument. In that constructor, you should call
  80         your parent class' archive constructor (even if your parent class is
  81         BArchivable).
  82
  83         \since BeOS R3
  84 */
  85
  86
  87 /*!
  88         \fn BArchivable::BArchivable()
  89         \brief Constructor. Does nothing.
  90
  91         \since BeOS R3
  92 */
  93
  94
  95 /*!
  96         \fn BArchivable::~BArchivable()
  97         \brief Destructor. Does nothing.
  98
  99         \since BeOS R3
 100 */
 101
 102
 103 /*!
 104         \fn virtual status_t BArchivable::Archive(BMessage* into, bool deep) const
 105         \brief Archive the object into a BMessage.
 106
 107         You should call this method from your derived implementation as it adds the
 108         data needed to instantiate your object to the message.
 109
 110         \param into The message you store your object in.
 111         \param deep If \c true, all children of this object should be archived as
 112                well.
 113
 114         \retval B_OK The archive operation was successful.
 115         \retval B_BAD_VALUE \c NULL \a archive message.
 116         \retval B_ERROR The archive operation failed.
 117
 118         \since BeOS R3
 119 */
 120
 121
 122 /*!
 123         \fn static BArchivable* BArchivable::Instantiate(BMessage* archive)
 124         \brief Static member to restore objects from messages.
 125
 126         You should always check that the \a archive argument actually corresponds to
 127         your class. The automatic functions, such as #instantiate_object() and
 128         BUnarchiver::InstantiateObject() will not choose the wrong class but manual
 129         calls to this member might be faulty. You can verify that \c archive
 130         stores an object of your class with the validate_instantiation() function.
 131
 132         \param archive The message with the data of the object to restore.
 133
 134         \return A pointer to a BArchivable object.
 135         \retval You should return a pointer to the object you create with
 136                 \c archive, or \c NULL if the unarchival fails.
 137
 138         \warning The default implementation will always return \c NULL. Even though
 139                 it is possible to store plain BArchivable objects, it is impossible to
 140                 restore them.
 141
 142         \see instantiate_object(BMessage*)
 143         \see BUnarchiver::InstantiateObject()
 144
 145         \since BeOS R3
 146 */
 147
 148
 149 /*!
 150         \fn virtual status_t BArchivable::Perform(perform_code d, void* arg)
 151         \brief Perform some action (Internal method defined for binary
 152                    compatibility purposes).
 153
 154         \internal This method is defined for binary compatibility purposes, it is
 155                   used to ensure that the correct AllUnarchived() and AllArchived()
 156                   methods are called for objects, as those methods are new to
 157                   Haiku.
 158
 159         \param d The perform code.
 160         \param arg A pointer to store some data.
 161
 162         \returns A status code.
 163
 164         \since Haiku R1
 165 */
 166
 167
 168 /*!
 169         \fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive)
 170         \brief Method relating to the use of \c BUnarchiver.
 171
 172         This hook function is called triggered in the BUnarchiver::Finish() method.
 173         In this method, you can rebuild references to objects that may be direct
 174         children of your object, or may be children of other objects.
 175         Implementations of this method should call the implementation of
 176         their parent class, the same as for the Archive() method.
 177
 178         \warning To guarantee that your AllUnarchived() method will be called
 179                  during unarchival, you must create a BUnarchiver object in your
 180                  archive constructor.
 181
 182         \see BUnarchiver, BUnarchiver::Finish()
 183
 184         \since Haiku R1
 185 */
 186
 187
 188 /*! \fn virtual status_t BArchivable::AllArchived(BMessage* into) const
 189         \brief Method relating to the use of \c BArchiver.
 190
 191         This hook function is called once the first BArchiver that was created in
 192         an archiving session is either destroyed, or has its Finish() method
 193         called. Implementations of this method can be used, in conjunction with
 194         BArchiver::IsArchived(), to reference objects in your archive that you
 195         do not own, depending on whether or not those objects were archived by their
 196         owners. Implementations of this method should call the implementation of
 197         their parent class, the same as for the Archive() method.
 198
 199         \warning To guarantee that your AllArchived() method will be called
 200                 during archival, you must create a BArchiver object in your
 201                 Archive() implementation.
 202
 203         \warning You should archive any objects you own in your Archive()
 204                 method implementation, and \b NOT your AllArchived() method.
 205
 206         \see BArchiver BArchiver::Finish()
 207
 208         \since Haiku R1
 209 */
 210
 211
 212 ///// BArchiver /////
 213
 214
 215 /*!
 216         \class BArchiver
 217         \ingroup support
 218         \ingroup libbe
 219         \brief A class that simplifies the archiving of complicated BArchivable
 220                hierarchies.
 221
 222         The BArchiver class is a small class that is used for archiving of
 223         complicated BArchivable hierarchies. Such a hierarchy may include
 224         multiple BArchivable objects, each of which might be referenced by
 225         many BArchivable objects. With the BArchiver class, you can be certain
 226         that each BArchivable object is archived only once with very little work.
 227         When used in conjuction with the BArchivable::AllArchived() and
 228         BArchivable::AllUnarchived() methods, it is simple to rebuild your system of
 229         references upon unarchival so that they are equivalent to those that were
 230         present in your original hierarchy.
 231
 232         The objects you archive can be retrieved using a BUnarchiver object.
 233
 234         \since Haiku R1
 235 */
 236
 237
 238 /*!
 239         \fn BArchiver::BArchiver(BMessage* archive)
 240         \brief Constructs a BArchiver object that manages \c archive.
 241
 242         \since Haiku R1
 243 */
 244
 245
 246 /*!
 247         \fn BArchiver::~BArchiver()
 248         \brief Destroys a BArchiver object. If the BArchiver object has not had its
 249                Finish() method called, this will be done now.
 250
 251         \since Haiku R1
 252 */
 253
 254
 255 /*!
 256         \fn status_t BArchiver::AddArchivable(const char* name,
 257                         BArchivable* archivable, bool deep = true)
 258         \brief Adds a reference to \c archivable to the archive used to
 259                construct this BArchiver. May call \c archivable's Archive() method.
 260
 261         \param name Where this reference will be stored in the archive.
 262         \param archivable The BArchivable* object that to reference.
 263         \param deep Passed to \c archivable->Archive() if \c archivable must
 264                be archived.
 265
 266         Adds a reference to \c archivable to your archive. If \c archivable has
 267         not yet been archived, then its Archive() method is called. BArchiver
 268         can only track BArchivable objects that have been archived through this
 269         method or the GetTokenForArchivable() methods.
 270
 271         \warning If you manually archive an object, and then pass it to
 272                  AddArchivable() or GetTokenForArchivable(), it will be archived
 273                  again, and when unarchived you will end up with two different
 274                  BArchivable objects.
 275
 276         \since Haiku R1
 277 */
 278
 279
 280 /*!
 281         \fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable,
 282                 bool deep, int32& _token);
 283         \brief Get a token representing a BArchivable object for this archiving
 284                session.
 285
 286         \param archivable The BArchivable object for which you wish to get a
 287                token.
 288         \param deep Controls how \c archivable will be archived, if it has not yet
 289                been archived in this session.
 290         \param[out] _token The token representing \c archivable is stored here.
 291
 292         Retrieves or creates a token to represent \c archivable in this archiving
 293         session. If \c archivable has not yet been archived, it will be now. If
 294         \c archivable gets archived, the \c deep parameter will be passed to its
 295         Archive() method.
 296
 297         \warning If you manually archive an object, and then pass it to
 298                  GetTokenForArchivable(), it will be archived again, and when
 299                  unarchived you will end up with two different BArchivable objects.
 300
 301         \since Haiku R1
 302 */
 303
 304
 305 /*!
 306         \fn status_t BArchiver::GetTokenForArchivable(BArchivable* archivable,
 307                 int32 &_token)
 308         \brief Equivalent to calling the expanded GetTokenForArchivable(
 309                BArchivable*, bool, int32&), with the deep parameter equal to
 310                \c true.
 311
 312         \see GetTokenForArchivable(BArchivable*, bool, int32&)
 313
 314         \since Haiku R1
 315 */
 316
 317
 318 /*!
 319         \fn bool BArchiver::IsArchived(BArchivable* archivable);
 320         \brief Returns whether \c archivable has already been archived in this
 321                session.
 322
 323         \return Whether or not the object has already been archived.
 324         \retval true \c archivable has been archived in this archiving session.
 325         \retval false \c archivable has not been archived in this archiving session.
 326
 327         \since Haiku R1
 328 */
 329
 330
 331 /*!
 332         \fn status_t BArchiver::Finish(status_t err = B_OK);
 333         \brief Report any archiving errors and possibly complete the archiving
 334                session.
 335
 336         This method may finish an archiving session (triggering the call of all
 337         archived objects' AllArchived() methods) if the following conditions
 338         are true:
 339         - No errors have been reported to this or any other BArchiver object
 340           within this session.
 341         - This is the last remaining BArchiver that has not had its Finish()
 342           method invoked.
 343
 344         If you call this method with an error code not equal to B_OK, then this
 345         archiving session has failed, archived objects will not have their
 346         AllArchived() methods called, and any subsequent calls to this method
 347         on any BArchiver objects in this session will return your error code.
 348
 349         \return The first error reported in this archiving session, or \c B_OK.
 350
 351         \since Haiku R1
 352 */
 353
 354
 355 /*!
 356         \fn const BMessage*     BArchiver::ArchiveMessage() const
 357         \brief Returns the BMessage* used to construct this BArchiver. This is
 358                the archive that AddArchivable() modifies.
 359
 360         \since Haiku R1
 361 */
 362
 363
 364 ///// BUnarchiver /////
 365
 366
 367 /*!
 368         \class BUnarchiver
 369         \ingroup support
 370         \ingroup libbe
 371         \brief A class that simplifies the unarchiving of complicated BArchivable
 372                hierarchies.
 373
 374         The BUnarchiver class is a small class used to recover BArchivable objects
 375         that have been archived with the BArchiver class. It also provides ownership
 376         semantics, so that memory leaks can be avoided during the unarchival
 377         process. When retrieving an object (either via GetObject() or FindObject()),
 378         you can specify a BUnarchiver::ownership_policy. If you specify
 379         BUnarchiver::B_ASSUME_OWNERSHIP, you will become responsible for deleting
 380         the retrieved item. If you specify BUnarchiver::B_DONT_ASSUME_OWNERSHIP,
 381         you will not become responsible. You cannot take ownership of the same
 382         object twice. After the unarchival process finishes, any unclaimed objects,
 383         excluding the root object (the object being instantiated via
 384         instantiate_object() or BUnarchiver::InstantiateObject()), will be deleted.
 385
 386         If you are updating a class that previously did not use the BArchiver and
 387         BUnarchiver helper classes, and want to maintain backwards compatibility
 388         with old archive, this can be done using the IsArchiveManaged() method.
 389
 390         \warning Calling methods on your BUnarchiver with a legacy archive (one
 391                  that was not managed by a BArchiver during archival) will result
 392                  in a call to debugger().
 393
 394         \since Haiku R1
 395 */
 396
 397
 398 /*!
 399         \fn BUnarchiver::BUnarchiver(const BMessage* archive)
 400         \brief Constructs a BUnarchiver object to manage \c archive.
 401
 402         \note To guarantee that your AllUnarchived() method will be called during
 403               archival, you must create a BUnarchiver object in your archive
 404               constructor. It is necessary to do this even if you won't use the
 405               BUnarchiver object in your archive constructor.
 406
 407         \warning Do not construct a BUnarchiver object without first calling
 408                  BUnarchiver::PrepareArchive() on \c archive. It is only safe to
 409                  build a BUnarchiver without this call in your AllUnarchived()
 410                  implementation.
 411
 412         \see BUnarchiver::PrepareArchive()
 413
 414         \since Haiku R1
 415 */
 416
 417
 418 /*!
 419         \fn BUnarchiver::~BUnarchiver()
 420         \brief Destroys a BUnarchiver object.
 421
 422         Calls this objects Finish() method, if it has not yet been called.
 423
 424         \since Haiku R1
 425 */
 426
 427
 428 /*!
 429         \fn status_t BUnarchiver::EnsureUnarchived(int32 token)
 430         \brief Ensure the object represented by \a token is unarchived and
 431                instantiated.
 432
 433         \param token the object \a token
 434
 435         \returns A status code.
 436
 437         \since Haiku R1
 438 */
 439
 440
 441 /*!
 442         \fn status_t BUnarchiver::EnsureUnarchived(const char* name,
 443                 int32 index = 0)
 444         \brief Ensure the object archived under \a name at \a index is unarchived
 445                and instantiated.
 446
 447         \param name The archive \a name.
 448         \param index The archive \a index.
 449
 450         \returns A status code.
 451
 452         \since Haiku R1
 453 */
 454
 455
 456 /*!
 457         \fn bool BUnarchiver::IsInstantiated(int32 token)
 458         \brief Checks whether the object represented by \c token has been
 459                instantiated in this session.
 460
 461         \param token The object \a token.
 462
 463         \returns \c true if instantiated, \c false otherwise
 464
 465         \since Haiku R1
 466 */
 467
 468
 469 /*!
 470         \fn bool BUnarchiver::IsInstantiated(const char* name, int32 index = 0)
 471         \brief Checks whether the object archived under \a name at \a index has been
 472                instantiated in this session.
 473
 474         \param name The archive \a name.
 475         \param index The arcive \a token.
 476
 477         \returns \c true if instantiated, \c false otherwise.
 478
 479         \since Haiku R1
 480 */
 481
 482
 483 /*!
 484         \fn template<class T> status_t BUnarchiver::GetObject(int32 token,
 485                 ownership_policy owning, T*& object)
 486         \brief Recover an object by token that was archived by a BArchiver object.
 487         If the object has not yet been instantiated, and this request is not coming
 488         from an AllUnarchived() implementation, the object will be instantiated now.
 489
 490         If the retrieved object is not of the type T, then this method will fail.
 491         If this method fails, you will not receive ownership of the object, no
 492         matter what you specified in \c owning.
 493
 494         \tparam T The type of \a object you wish to find.
 495
 496         \param token The \a token you got for this object from
 497                BArchiver::GetTokenForArchivable() during archival.
 498         \param owning Whether or not you wish to take ownership of the
 499                retrieved object.
 500         \param object Return parameter for the retrieved object of type T.
 501
 502         \returns A status code.
 503         \retval B_OK The object retrieved was of type T.
 504         \retval B_BAD_TYPE The object retrieved was not of type T.
 505
 506         \since Haiku R1
 507 */
 508
 509
 510 /*!
 511         \fn template<class T> status_t BUnarchiver::GetObject(int32 token,
 512                 T*& object)
 513         \brief Recover and take ownership of an object represented by \a token.
 514
 515         Equivalent to calling GetObject(token, \c B_ASSUME_OWNERSHIP, object)
 516
 517         \tparam T The type of \a object you wish to find.
 518
 519         \param token The \a token you got for this object from
 520                BArchiver::GetTokenForArchivable() during archival.
 521         \param object The return parameter for the retrieved object of type T.
 522
 523         \returns A status code.
 524         \retval B_OK The object retrieved was of type T.
 525         \retval B_BAD_TYPE The object retrieved was not of type T.
 526
 527         \since Haiku R1
 528 */
 529
 530
 531 /*!
 532         \fn template<class T> status_t BUnarchiver::FindObject(const char* name,
 533                 int32 index, ownership_policy owning, T*& object)
 534         \brief Recover an object that had previously been archived using
 535                the BArchiver::AddArchivable() method.
 536
 537         If the object has not yet been instantiated, and this request is not
 538         coming from an AllUnarchived() implementation, the object will be
 539         instantiated now.
 540
 541         If the retrieved object is not of the type T, then this method will fail.
 542         If this method fails, you will not receive ownership of the object, no
 543         matter what you specified in \c owning.
 544
 545         \tparam T The type of object you wish to find.
 546
 547         \param name The name that was passed to BArchiver::AddArchivable() when
 548                adding this object.
 549         \param index The index of the object you wish to recover (\c 0-based,
 550                like BMessage::FindData().
 551         \param owning Dictates whether or not you wish to take ownership of the
 552                retrieved object.
 553         \param object Return parameter for the retrieved object of type T.
 554
 555         \returns A status code.
 556         \retval B_OK The object retrieved was of type T.
 557         \retval B_BAD_TYPE The object retrieved was not of type T.
 558
 559         \since Haiku R1
 560 */
 561
 562
 563 /*!
 564         \fn template<class T> status_t BUnarchiver::FindObject(const char* name,
 565                 int32 index, T*& object)
 566         \brief Recover and take ownership of an object that had previously been
 567                archived using the BArchiver::AddArchivable() method.
 568
 569         \tparam T The type of object you wish to find.
 570
 571         \param name The name that was passed to BArchiver::AddArchivable() when
 572                adding this object.
 573         \param index The index of the object you wish to recover (\c 0-based,
 574                like #BMessage::FindData().
 575         \param object Return parameter for the retrieved object of type T.
 576
 577         \returns A status code.
 578         \retval B_OK The object retrieved was of type T.
 579         \retval B_BAD_TYPE The object retrieved was not of type T.
 580
 581         \since Haiku R1
 582 */
 583
 584
 585 /*!
 586         \fn template<class T> status_t BUnarchiver::FindObject(const char* name,
 587                 ownership_policy owning, T*& object)
 588         \brief Recover an object at index \c 0 that had previously been
 589                archived using the BArchiver::AddArchivable() method.
 590
 591         Equivalent to calling FindObject(name, \c 0, owning, object).
 592
 593         \tparam T The type of \a object you wish to find.
 594
 595         \param name The name that was passed to BArchiver::AddArchivable() when
 596                adding this object.
 597         \param owning Dictates whether or not you wish to take ownership of the
 598                retrieved object.
 599         \param object Return parameter for the retrieved object of type T.
 600
 601         \returns A status code.
 602         \retval B_OK The object retrieved was of type T.
 603         \retval B_BAD_TYPE The object retrieved was not of type T.
 604
 605         \since Haiku R1
 606 */
 607
 608
 609 /*!
 610         \fn template<class T> status_t BUnarchiver::FindObject(const char* name,
 611                 T*& object)
 612         \brief Recover and take ownership of an object at index \c 0 that had
 613                 previously been archived using the BArchiver::AddArchivable() method.
 614
 615         Equivalent to calling FindObject(name, \c 0,
 616         BUnarchiver::B_ASSUME_OWNERSHIP, object).
 617
 618         \tparam T The type of \a object you wish to find.
 619
 620         \param name The name that was passed to BArchiver::AddArchivable() when
 621                adding this object.
 622         \param object Return parameter for the retrieved \a object of type T.
 623
 624         \returns A status code.
 625         \retval B_OK The \a object retrieved was of type T.
 626         \retval B_BAD_TYPE The \a object retrieved was not of type T.
 627
 628         \since Haiku R1
 629 */
 630
 631
 632 /*!
 633         \fn status_t BUnarchiver::Finish(status_t err = B_OK);
 634         \brief Report any unarchiving errors and possibly complete the archiving
 635                session.
 636
 637         This method may finish an unarchiving session (triggering the call of all
 638         instantiated objects' AllUnarchived() methods) if the following conditions
 639         are true:
 640
 641         - No errors have been reported to this or any other BUnarchiver
 642           object within this session.
 643         - This is the last remaining BUnarchiver that has not had its
 644           Finish() method invoked.
 645
 646         If you call this method with an error code not equal to B_OK, then this
 647         unarchiving session has failed, instantiated objects will not have their
 648         AllUnarchived() methods called, and any subsequent calls to this method
 649         on any BUnarchiver objects in this session will return your error code.
 650         Furthermore, any objects that have been instantiated, but have not had
 651         their ownership assumed by another object will now be deleted (excluding
 652         the root object).
 653
 654         \return The first error reported in this unarchiving session, or \c B_OK.
 655
 656         \since Haiku R1
 657 */
 658
 659
 660 /*!
 661         \fn const BMessage* BUnarchiver::ArchiveMessage() const
 662         \brief Returns the BMessage* used to construct this BUnarchiver.
 663
 664         This is the archive that FindObject() uses.
 665 */
 666
 667
 668 /*!
 669         \fn static bool BUnarchiver::IsArchiveManaged(const BMessage* archive)
 670         \brief Checks whether \a archive was managed by a BArchiver object.
 671
 672         This method can be used to maintain archive backwards-compatibility for a
 673         class that has been updated to use the BArchiver class. If there is a
 674         possibility that you are may dealing with a legacy archive, you can use
 675         this method to find out before calling any methods on your BUnarchiver
 676         object.
 677
 678         Here is an example of how you might use this method. Note that you
 679         must still call PrepareArchive(archive) either way.
 680
 681 \code
 682 MyArchivableClas::MyArchivableClass(BMessage* archive)
 683     :
 684     BArchivable(BUnarchiver::PrepareArchive(archive))
 685 {
 686     BUnarchiver unarchiver(archive);
 687
 688     if (BUnarchiver::IsArchiveManaged(archive)) {
 689         // ... calls to FindObject() or GetObject() here ...
 690     } else {
 691         // ... calls to BMessage::FindMessage() here ...
 692     }
 693 }
 694 \endcode
 695
 696         \returns Whether \a archive was managed by a BArchiver object.
 697         \retval true if \a archive was managed by a BArchiver object.
 698         \retval false otherwise.
 699
 700         \since Haiku R1
 701 */
 702
 703
 704 /*!
 705         \fn static BMessage* BUnarchiver::PrepareArchive(BMessage* &archive)
 706         \brief Prepares \c archive for use by a BUnarchiver.
 707
 708         This method must be called if you plan to use a BUnarchiver on an archive.
 709         It must be called once for each class an object inherits from that
 710         will use a BUnarchiver.
 711
 712         \warning This method \b must be called \b before a call to the
 713                 archive constructor of your parent class.
 714
 715         Notice the use of this method in the example provided below.
 716 \code
 717 MyArchivableClas::MyArchivableClas(BMessage* archive)
 718     :
 719     BArchivable(BUnarchiver::PrepareArchive(archive))
 720 {
 721     // ...
 722 }
 723 \endcode
 724
 725         \param archive The archive you wish to have prepared.
 726
 727         \return The same #BMessage as is passed in.
 728
 729         \since Haiku R1
 730 */
 731
 732
 733 /*!
 734         \fn void BUnarchiver::AssumeOwnership(BArchivable* archivable)
 735         \brief Become the owner of \a archivable.
 736
 737         After calling this method you are responsible for deleting the
 738         \a archivable.
 739
 740         \param archivable The \a archivable object.
 741
 742         \since Haiku R1
 743 */
 744
 745
 746 /*!
 747         \fn void BUnarchiver::RelinquishOwnership(BArchivable* archivable)
 748         \brief Relinquish ownership of \a archivable. If \a archivable remains
 749                unclaimed at the end of the unarchiving session, it will be deleted
 750                (unless it is the root object).
 751
 752         \param archivable The \a archivable object.
 753
 754         \since Haiku R1
 755 */
 756
 757
 758 /*!
 759         \fn template<class T> status_t BUnarchiver::InstantiateObject(
 760                 BMessage* from, T*& object)
 761         \brief Attempt to instantiate an object of type T from BMessage*
 762                \a from.
 763
 764         If the instantiated object is not of type T, then it will be deleted,
 765         and this method will return \c B_BAD_TYPE. This method is similar to
 766         the instantiate_object() function, but provides error reporting and
 767         protection from memory leaks.
 768
 769         \param from The #BMessage to instantiate from.
 770         \param object Return parameter for the retrieved object of type T.
 771
 772         \returns A status code.
 773         \retval B_OK The object retrieved was of type T.
 774         \retval B_BAD_TYPE The object retrieved was not of type T.
 775
 776         \since Haiku R1
 777 */
 778
 779
 780 ///// Global methods /////
 781
 782
 783 /*!
 784         \addtogroup support_globals
 785 */
 786
 787
 788 //! @{
 789
 790
 791 /*!
 792         \typedef typedef BArchivable* (*instantiation_func)(BMessage*)
 793         \brief Internal definition of a function that can instantiate objects that
 794                have been created with the BArchivable API.
 795
 796         \since BeOS R3
 797 */
 798
 799
 800 /*!
 801         \fn BArchivable* instantiate_object(BMessage *from, image_id *id)
 802         \brief Instantiate an archived object with the object being defined in a
 803                different application or library.
 804
 805         This function is similar to instantiate_object(BMessage *from), except that
 806         it takes the \a id argument referring to an image where the object might be
 807         stored.
 808
 809         \note Images are names for executable files. Image id's refer to these
 810               executable files that have been loaded by your application. Have a
 811               look at the kernel API for further information.
 812
 813         \since BeOS R3
 814 */
 815
 816
 817 /*!
 818         \fn BArchivable* instantiate_object(BMessage *from)
 819         \brief Instantiate an archived object.
 820
 821         This global function will determine the base class, based on the \a from
 822         argument, and it will call the Instantiate() function of that object to
 823         restore it.
 824
 825         \param from The archived object.
 826
 827         \return The object returns a pointer to the instantiated object, or \c NULL
 828                 if the instantiation failed. The global \c errno variable will
 829                 contain the reason why it failed.
 830
 831         \see instantiate_object(BMessage *from, image_id *id)
 832
 833         \since BeOS R3
 834 */
 835
 836
 837 /*!
 838         \fn bool validate_instantiation(BMessage* from, const char* className)
 839         \brief Internal function that checks if the \a className is the same as the
 840                one stored in the \a from message.
 841
 842         \since BeOS R3
 843 */
 844
 845
 846 /*!
 847         \fn instantiation_func find_instantiation_func(const char* className,
 848                 const char* signature)
 849         \brief Internal function that searches for the instantiation func with a
 850                specific signature. Use instantiate_object() instead.
 851
 852         \since Haiku R1
 853 */
 854
 855
 856 /*!
 857         \fn instantiation_func find_instantiation_func(const char* className)
 858         \brief Internal function that searches for the instantiation func of a
 859                specific class. Use instantiate_object() instead.
 860
 861         \since BeOS R3
 862 */
 863
 864
 865 /*!
 866         \fn instantiation_func find_instantiation_func(BMessage* archive)
 867         \brief Internal function that searches for the instantiation func that
 868                works on the specified \a archive. Use instantiate_object() instead.
 869
 870         \since BeOS R3
 871 */
 872
 873
 874 //! @}