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/*! \fn BArchivable::BArchivable(BMessage* from) 67 \brief Constructor. Does important behind-the-scenes work in the unarchiving 68 process. 69 70 If you inherit this interface you should provide at least one constructor 71 that takes one BMessage argument. In that constructor, you should call your 72 parent class' archive constructor (even if your parent class is 73 BArchivable). 74*/ 75 76 77/*! \fn BArchivable::BArchivable() 78 \brief Constructor. Does nothing. 79*/ 80 81 82/*! \fn BArchivable::~BArchivable() 83 \brief Destructor. Does nothing. 84*/ 85 86 87/*! \fn virtual status_t BArchivable::Archive(BMessage* into, 88 bool deep = true) const 89 \brief Archive the object into a BMessage. 90 91 You should call this method from your derived implementation as it adds the 92 data needed to instantiate your object to the message. 93 94 \param into The message you store your object in. 95 \param deep If \c true, all children of this object should be archived as 96 well. 97 \retval B_OK The archiving succeeded. 98 \retval "error codes" The archiving did not succeed. 99*/ 100 101 102/*! \fn static BArchivable* BArchivable::Instantiate(BMessage* archive) 103 \brief Static member to restore objects from messages. 104 105 You should always check that the \a archive argument actually corresponds to 106 your class. The automatic functions, such as #instantiate_object() and 107 BUnarchiver::InstantiateObject() will not choose the wrong class but manual 108 calls to this member might be faulty. You can verify that \c archive 109 stores an object of your calss with the validate_instantiation() function. 110 111 \param archive The message with the data of the object to restore. 112 \retval You should return a pointer to the object you create with 113 \c archive, or \c NULL if unarchival fails. 114 \warning The default implementation will always return \c NULL. Even though 115 it is possible to store plain BArchivable objects, it is impossible to 116 restore them. 117 118 \see instantiate_object(BMessage *from) 119 \see BUnarchiver::InstantiateObject() 120*/ 121 122 123/*! \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) 124 \brief Internal method defined for binary compatibility purposes. 125 \internal This method is defined for binary compatibility purposes, it is 126 used to ensure that the correct AllUnarchived() and AllArchived() 127 methods are called for objects, as those methods are new to Haiku. 128*/ 129 130 131/*! \fn virtual status_t BArchivable::AllUnarchived(const BMessage* archive) 132 \brief Method relating to the use of \c BUnarchiver. 133 134 This hook function is called triggered in the BUnarchiver::Finish() method. 135 In this method, you can rebuild references to objects that may be direct 136 children of your object, or may be children of other objects. 137 Implementations of this method should call the implementation of 138 their parent class, the same as for the Archive() method. 139 140 \warning To guarantee that your AllUnarchived() method will be called 141 during unarchival, you must create a BUnarchiver object in your 142 archive constructor. 143 144 \see BUnarchiver, BUnarchiver::Finish() 145*/ 146 147 148/*! \fn virtual status_t BArchivable::AllArchived(BMessage* into) const 149 \brief Method relating to the use of \c BArchiver. 150 151 This hook function is called once the first BArchiver that was created in 152 an archiving session is either destroyed, or has its Finish() method 153 called. Implementations of this method can be used, in conjunction with 154 BArchiver::IsArchived(), to reference objects in your archive that you 155 do not own, depending on whether or not those objects were archived by their 156 owners. Implementations of this method should call the implementation of 157 their parent class, the same as for the Archive() method. 158 159 \warning To guarantee that your AllArchived() method will be called 160 during archival, you must create a BArchiver object in your 161 Archive() implementation. 162 163 \warning You should archive any objects you own in your Archive() 164 method implementation, and \b NOT your AllArchived() method. 165 166 \see BArchiver BArchiver::Finish() 167*/ 168 169 170///// Global methods ///// 171/*! 172 \addtogroup support_globals 173 @{ 174*/ 175 176 177/*! \typedef typedef BArchivable* (*instantiation_func)(BMessage*) 178 \brief Internal definition of a function that can instantiate objects that 179 have been created with the BArchivable API. 180*/ 181 182 183/*! \fn BArchivable* instantiate_object(BMessage *from, image_id *id) 184 \brief Instantiate an archived object with the object being defined in a 185 different application or library. 186 187 This function is similar to instantiate_object(BMessage *from), except that 188 it takes the \a id argument referring to an image where the object might be 189 stored. 190 191 \note Images are names for executable files. Image id's refer to these 192 executable files that have been loaded by your application. Have a look 193 at the kernel API for further information. 194*/ 195 196 197/*! \fn BArchivable* instantiate_object(BMessage *from) 198 \brief Instantiate an archived object. 199 200 This global function will determine the base class, based on the \a from 201 argument, and it will call the Instantiate() function of that object to 202 restore it. 203 204 \param from The archived object. 205 \return The object returns a pointer to the instantiated object, or \c NULL 206 if the instantiation failed. The global \c errno variable will contain 207 the reason why it failed. 208 \see instantiate_object(BMessage *from, image_id *id) 209*/ 210 211 212/*! \fn bool validate_instantiation(BMessage* from, const char* className) 213 \brief Internal function that checks if the \a className is the same as the 214 one stored in the \a from message. 215*/ 216 217 218/*! \fn instantiation_func find_instantiation_func(const char* className, 219 const char* signature) 220 \brief Internal function that searches for the instantiation func with a 221 specific signature. Use instantiate_object() instead. 222*/ 223 224 225/*! \fn instantiation_func find_instantiation_func(const char* className) 226 \brief Internal function that searches for the instantiation func of a 227 specific class. Use instantiate_object() instead. 228*/ 229 230 231/*! \fn instantiation_func find_instantiation_func(BMessage* archive) 232 \brief Internal function that searches for the instantiation func that 233 works on the specified \a archive. Use instantiate_object() instead. 234*/ 235 236 237//! @} 238