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