1/* 2 * Copyright 2007, Haiku, Inc. All Rights Reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Author: 6 * Niels Sascha Reedijk <niels.reedijk@gmail.com> 7 * 8 * Proofreader: 9 * David Weizades <ddewbofh@hotmail.com> 10 * Thom Holwerda <slakje@quicknet.nl> 11 * 12 * Corresponds to: 13 * /trunk/headers/os/support/Archivable.h rev 19972 14 * /trunk/src/kits/support/Archivable.cpp rev 19095 15 */ 16 17/*! 18 \file Archivable.h 19 \brief Provides the BArchivable interface. 20*/ 21 22/*! 23 \class BArchivable 24 \ingroup support 25 \ingroup libbe 26 \brief Interface for objects that can be archived into a BMessage. 27 28 BArchivable provides an interface for objects that can be put into message 29 archives and extracted into objects in another location. Using this you are 30 able to send objects between applications, or even between computers across 31 networks. 32 33 BArchivable differs from BFlattenable in that BFlattenable is designed to 34 store objects into flat streams of data, the main objective being storage to 35 disk. The objective of this interface, however, is to store objects that will 36 be restored to other objects. To illustrate this point, BArchivable messages 37 know how to restore themselves whereas BFlattenables have a datatype which 38 you need to map to classes manually. 39 40 Archiving is done with the Archive() method. If your class supports it, the 41 caller can request it to store into a deep archive, meaning that all child 42 objects in it will be stored. Extracting the archive works with the 43 Instantiate() method, which is static. Since the interface is designed to 44 extract objects without the caller knowing what kind of object it actually is, 45 the global function #instantiate_object() instantiates a message without you 46 manually having to determine the class the message is from. This adds 47 considerable flexibility and allows BArchivable to be used in combination with 48 other add-ons. 49 50 To provide this interface in your classes you should publicly inherit this 51 class. You should implement Archive() and Instantiate(), and provide one 52 constructor that takes one BMessage argument. 53*/ 54 55/*! 56 \fn BArchivable::BArchivable(BMessage* from) 57 \brief Constructor. Does nothing. 58 59 If you inherit this interface you should provide at least one constructor that 60 takes one BMessage argument. 61*/ 62 63/*! 64 \fn BArchivable::BArchivable() 65 \brief Constructor. Does nothing. 66*/ 67 68/*! 69 \fn BArchivable::~BArchivable() 70 \brief Destructor. Does nothing. 71*/ 72 73/*! 74 \fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const 75 \brief Archive the object into a BMessage. 76 77 You should call this method from your derived implementation as it adds the 78 data needed to instantiate your object to the message. 79 80 \param into The message you store your object in. 81 \param deep If \c true, all children of this object should be stored as well. 82 Only pay attention to this parameter if you actually have child objects. 83 \retval B_OK The archiving succeeded. 84 \retval "error codes" The archiving did not succeed. 85*/ 86 87/*! 88 \fn static BArchivable* BArchivable::Instantiate(BMessage* archive) 89 \brief Static member to restore objects from messages. 90 91 You should always check that the \a archive argument actually corresponds to 92 your class. The automatic functions, such as #instantiate_object() will not 93 choose the wrong class but manual calls to this member might be faulty. 94 95 \param archive The message with the data of the object to restore. 96 \retval You should return a pointer to your object, or \c NULL if you 97 fail. 98 \warning The default implementation will always return \c NULL. Even though 99 it is possible to store plain BArchive objects, it is impossible to restore 100 them. 101 \see instantiate_object(BMessage *from) 102*/ 103 104/*! 105 \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) 106 \brief Internal method. 107 \internal This method is defined in case of unforeseen binary compatibility 108 API issues. Currently nothing of interest is implemented. 109*/ 110 111///// Global methods ///// 112/*! 113 \addtogroup support_globals 114 @{ 115*/ 116 117/*! 118 \typedef typedef BArchivable* (*instantiation_func)(BMessage*) 119 \brief Internal definition of a function that can instantiate objects that 120 have been created with the BArchivable API. 121*/ 122 123/*! 124 \fn BArchivable* instantiate_object(BMessage *from, image_id *id) 125 \brief Instantiate an archived object with the object being defined in a 126 different application or library. 127 128 This function is similar to instantiate_object(BMessage *from), except that 129 it takes the \a id argument referring to an image where the object might be 130 stored. 131 132 \note Images are names for executable files. Image id's refer to these 133 executable files that have been loaded by your application. Have a look 134 at the kernel API for further information. 135*/ 136 137/*! 138 \fn BArchivable* instantiate_object(BMessage *from) 139 \brief Instantiate an archived object. 140 141 This global function will determine the base class, based on the \a from 142 argument, and it will call the Instantiate() function of that object to 143 restore it. 144 145 \param from The archived object. 146 \return The object returns a pointer to the instantiated object, or \c NULL 147 if the instantiation failed. The global \c errno variable will contain the 148 reason why it failed. 149 \see instantiate_object(BMessage *from, image_id *id) 150*/ 151 152/*! 153 \fn bool validate_instantiation(BMessage* from, const char* className) 154 \brief Internal function that checks if the \a className is the same as the 155 one stored in the \a from message. 156*/ 157 158/*! 159 \fn instantiation_func find_instantiation_func(const char* className, const char* signature) 160 \brief Internal function that searches for the instantiation func with a 161 specific signature. Use instantiate_object() instead. 162*/ 163 164/*! 165 \fn instantiation_func find_instantiation_func(const char* className) 166 \brief Internal function that searches for the instantiation func of a 167 specific class. Use instantiate_object() instead. 168*/ 169 170/*! 171 \fn instantiation_func find_instantiation_func(BMessage* archive) 172 \brief Internal function that searches for the instantiation func that 173 works on the specified \a archive. Use instantiate_object() instead. 174*/ 175 176//! @} 177