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 * 9 * Proofreader: 10 * David Weizades, ddewbofh@hotmail.com 11 * Thom Holwerda, slakje@quicknet.nl 12 * 13 * Corresponds to: 14 * /trunk/headers/os/support/Archivable.h rev 37751 15 * /trunk/src/kits/support/Archivable.cpp rev 37751 16 */ 17 18 19/*! 20 \file Archivable.h 21 \brief Provides the BArchivable interface and declares the BArchiver and 22 BUnarchiver classes. 23*/ 24 25 26/*! 27 \class BArchivable 28 \ingroup support 29 \ingroup libbe 30 \brief Interface for objects that can be archived into a BMessage. 31 32 BArchivable provides an interface for objects that can be put into message 33 archives and extracted into objects in another location. Using this you are 34 able to send objects between applications, or even between computers across 35 networks. 36 37 BArchivable differs from BFlattenable in that BFlattenable is designed to 38 store objects into flat streams of data, the main objective being storage to 39 disk. The objective of this interface, however, is to store objects that 40 will later be restored as new (but identical) objects. To illustrate this 41 point, BArchivable objects can be restored automatically to the correct 42 class, whereas BFlattenables have a data type which you need to map to 43 classes manually. 44 45 Archiving is done with the Archive() method. If your class supports it, the 46 caller can request it to store into a deep archive, meaning that all child 47 objects in it will be stored. Extracting the archive works with the 48 Instantiate() method, which is static. Since the interface is designed to 49 extract objects without the caller knowing what kind of object it actually 50 is, the global function #instantiate_object() instantiates a message without 51 you manually having to determine the class the message is from. This adds 52 considerable flexibility and allows BArchivable to be used in combination 53 with other add-ons. 54 55 To provide this interface in your classes you should publicly inherit this 56 class. You should implement Archive() and Instantiate(), and provide one 57 constructor that takes one BMessage argument. 58 59 If your class holds references to other BArchivable objects that you wish 60 to archive, then you should consider using the BArchiver and BUnarchiver 61 classes in your Archive() method and archive constructor, respectively. 62 You should also consider implementing the AllArchived() and AllUnarchived() 63 methods, which were designed to ease archiving and unarchiving in such 64 a situation. 65*/ 66 67 68/*! 69 \fn BArchivable::BArchivable(BMessage* from) 70 \brief Constructor. Does important behind-the-scenes work in the unarchiving 71 process. 72 73 If you inherit this interface you should provide at least one constructor 74 that takes one BMessage argument. In that constructor, you should call your 75 parent class' archive constructor (even if your parent class is 76 BArchivable). 77*/ 78 79 80/*! 81 \fn BArchivable::BArchivable() 82 \brief Constructor. Does nothing. 83*/ 84 85 86/*! 87 \fn BArchivable::~BArchivable() 88 \brief Destructor. Does nothing. 89*/ 90 91 92/*! 93 \fn virtual status_t BArchivable::Archive(BMessage* into, 94 bool deep = true) const 95 \brief Archive the object into a BMessage. 96 97 You should call this method from your derived implementation as it adds the 98 data needed to instantiate your object to the message. 99 100 \param into The message you store your object in. 101 \param deep If \c true, all children of this object should be archived as 102 well. 103 \retval B_OK The archiving succeeded. 104 \retval "error codes" The archiving did not succeed. 105*/ 106 107 108/*! 109 \fn static BArchivable* BArchivable::Instantiate(BMessage* archive) 110 \brief Static member to restore objects from messages. 111 112 You should always check that the \a archive argument actually corresponds to 113 your class. The automatic functions, such as #instantiate_object() and 114 BUnarchiver::InstantiateObject() will not choose the wrong class but manual 115 calls to this member might be faulty. You can verify that \c archive 116 stores an object of your calss with the validate_instantiation() function. 117 118 \param archive The message with the data of the object to restore. 119 \retval You should return a pointer to the object you create with 120 \c archive, or \c NULL if unarchival fails. 121 \warning The default implementation will always return \c NULL. Even though 122 it is possible to store plain BArchivable objects, it is impossible to 123 restore them. 124 125 \see instantiate_object(BMessage *from) 126 \see BUnarchiver::InstantiateObject() 127*/ 128 129 130/*! 131 \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) 132 \brief Internal method. 133 \internal This method is defined for binary compatibility purposes, it is 134 used to ensure that the correct AllUnarchived() and AllArchived() 135 methods are called for objects, as those methods are new to Haiku. 136*/ 137 138 139/*! 140 \fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive) 141 \brief Method relating to the use of \c BUnarchiver. 142 143 This hook function is called triggered in the BUnarchiver::Finish() method. 144 In this method, you can rebuild references to objects that may be direct 145 children of your object, or may be children of other objects. 146 Implementations of this method should call the implementation of 147 their parent class, the same as for the Archive() method. 148 149 \note To guarantee that your AllUnarchived() method will be called during 150 unarchival, you must create a BUnarchiver object in your archive 151 constructor. 152 153 \see BUnarchiver, BUnarchiver::Finish() 154*/ 155 156 157/*! 158 \fn virtual status_t BArchivable::AllArchived(BMessage* into) const 159 \brief Method relating to the use of \c BArchiver. 160 161 This hook function is called once the first BArchiver that was created in 162 an archiving session is either destroyed, or has its \c Finish() method 163 called. Implementations of this method can be used, in conjunction with 164 BArchiver::IsArchived(), to reference objects in your archive that you 165 do not own, depending on whether or not those objects were archived by their 166 owners. Implementations of this method should call the implementation of 167 their parent class, the same as for the Archive() method. 168 169 \note To guarantee that your AllArchived() method will be called during 170 archival, you must create a BArchiver object in your Archive() 171 implementation. 172 173 \note You should archive any objects you own in your Archive() method 174 implementation, \b NOT your AllArchived() method. 175 176 \see BArchiver BArchiver::Finish() 177*/ 178 179 180///// Global methods ///// 181/*! 182 \addtogroup support_globals 183 @{ 184*/ 185 186 187/*! 188 \typedef typedef BArchivable* (*instantiation_func)(BMessage*) 189 \brief Internal definition of a function that can instantiate objects that 190 have been created with the BArchivable API. 191*/ 192 193 194/*! 195 \fn BArchivable* instantiate_object(BMessage *from, image_id *id) 196 \brief Instantiate an archived object with the object being defined in a 197 different application or library. 198 199 This function is similar to instantiate_object(BMessage *from), except that 200 it takes the \a id argument referring to an image where the object might be 201 stored. 202 203 \note Images are names for executable files. Image id's refer to these 204 executable files that have been loaded by your application. Have a look 205 at the kernel API for further information. 206*/ 207 208 209/*! 210 \fn BArchivable* instantiate_object(BMessage *from) 211 \brief Instantiate an archived object. 212 213 This global function will determine the base class, based on the \a from 214 argument, and it will call the Instantiate() function of that object to 215 restore it. 216 217 \param from The archived object. 218 \return The object returns a pointer to the instantiated object, or \c NULL 219 if the instantiation failed. The global \c errno variable will contain 220 the reason why it failed. 221 \see instantiate_object(BMessage *from, image_id *id) 222*/ 223 224 225/*! 226 \fn bool validate_instantiation(BMessage* from, const char* className) 227 \brief Internal function that checks if the \a className is the same as the 228 one stored in the \a from message. 229*/ 230 231 232/*! 233 \fn instantiation_func find_instantiation_func(const char* className, 234 const char* signature) 235 \brief Internal function that searches for the instantiation func with a 236 specific signature. Use instantiate_object() instead. 237*/ 238 239 240/*! 241 \fn instantiation_func find_instantiation_func(const char* className) 242 \brief Internal function that searches for the instantiation func of a 243 specific class. Use instantiate_object() instead. 244*/ 245 246 247/*! 248 \fn instantiation_func find_instantiation_func(BMessage* archive) 249 \brief Internal function that searches for the instantiation func that 250 works on the specified \a archive. Use instantiate_object() instead. 251*/ 252 253 254//! @} 255