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