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/*! 19 \file Archivable.h 20 \brief Provides the BArchivable interface. 21*/ 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 be restored to other objects. To illustrate this point, BArchivable 39 messages know how to restore themselves whereas BFlattenables have a 40 datatype which you need to map to classes manually. 41 42 Archiving is done with the Archive() method. If your class supports it, the 43 caller can request it to store into a deep archive, meaning that all child 44 objects in it will be stored. Extracting the archive works with the 45 Instantiate() method, which is static. Since the interface is designed to 46 extract objects without the caller knowing what kind of object it actually 47 is, the global function #instantiate_object() instantiates a message without 48 you manually having to determine the class the message is from. This adds 49 considerable flexibility and allows BArchivable to be used in combination 50 with other add-ons. 51 52 To provide this interface in your classes you should publicly inherit this 53 class. You should implement Archive() and Instantiate(), and provide one 54 constructor that takes one BMessage argument. 55*/ 56 57 58/*! 59 \fn BArchivable::BArchivable(BMessage* from) 60 \brief Constructor. Does nothing. 61 62 If you inherit this interface you should provide at least one constructor 63 that takes one BMessage argument. 64*/ 65 66 67/*! 68 \fn BArchivable::BArchivable() 69 \brief Constructor. Does nothing. 70*/ 71 72 73/*! 74 \fn BArchivable::~BArchivable() 75 \brief Destructor. Does nothing. 76*/ 77 78 79/*! 80 \fn virtual status_t BArchivable::Archive(BMessage* into, 81 bool deep = true) const 82 \brief Archive the object into a BMessage. 83 84 You should call this method from your derived implementation as it adds the 85 data needed to instantiate your object to the message. 86 87 \param into The message you store your object in. 88 \param deep If \c true, all children of this object should be stored as 89 well. Only pay attention to this parameter if you actually have child 90 objects. 91 \retval B_OK The archiving succeeded. 92 \retval "error codes" The archiving did not succeed. 93*/ 94 95 96/*! 97 \fn static BArchivable* BArchivable::Instantiate(BMessage* archive) 98 \brief Static member to restore objects from messages. 99 100 You should always check that the \a archive argument actually corresponds to 101 your class. The automatic functions, such as #instantiate_object() will not 102 choose the wrong class but manual calls to this member might be faulty. 103 104 \param archive The message with the data of the object to restore. 105 \retval You should return a pointer to your object, or \c NULL if you 106 fail. 107 \warning The default implementation will always return \c NULL. Even though 108 it is possible to store plain BArchive objects, it is impossible to 109 restore them. 110 \see instantiate_object(BMessage *from) 111*/ 112 113 114/*! 115 \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) 116 \brief Internal method. 117 \internal This method is defined in case of unforeseen binary compatibility 118 API issues. Currently nothing of interest is implemented. 119*/ 120 121 122///// Global methods ///// 123/*! 124 \addtogroup support_globals 125 @{ 126*/ 127 128 129/*! 130 \typedef typedef BArchivable* (*instantiation_func)(BMessage*) 131 \brief Internal definition of a function that can instantiate objects that 132 have been created with the BArchivable API. 133*/ 134 135 136/*! 137 \fn BArchivable* instantiate_object(BMessage *from, image_id *id) 138 \brief Instantiate an archived object with the object being defined in a 139 different application or library. 140 141 This function is similar to instantiate_object(BMessage *from), except that 142 it takes the \a id argument referring to an image where the object might be 143 stored. 144 145 \note Images are names for executable files. Image id's refer to these 146 executable files that have been loaded by your application. Have a look 147 at the kernel API for further information. 148*/ 149 150 151/*! 152 \fn BArchivable* instantiate_object(BMessage *from) 153 \brief Instantiate an archived object. 154 155 This global function will determine the base class, based on the \a from 156 argument, and it will call the Instantiate() function of that object to 157 restore it. 158 159 \param from The archived object. 160 \return The object returns a pointer to the instantiated object, or \c NULL 161 if the instantiation failed. The global \c errno variable will contain 162 the reason why it failed. 163 \see instantiate_object(BMessage *from, image_id *id) 164*/ 165 166 167/*! 168 \fn bool validate_instantiation(BMessage* from, const char* className) 169 \brief Internal function that checks if the \a className is the same as the 170 one stored in the \a from message. 171*/ 172 173 174/*! 175 \fn instantiation_func find_instantiation_func(const char* className, 176 const char* signature) 177 \brief Internal function that searches for the instantiation func with a 178 specific signature. Use instantiate_object() instead. 179*/ 180 181 182/*! 183 \fn instantiation_func find_instantiation_func(const char* className) 184 \brief Internal function that searches for the instantiation func of a 185 specific class. Use instantiate_object() instead. 186*/ 187 188 189/*! 190 \fn instantiation_func find_instantiation_func(BMessage* archive) 191 \brief Internal function that searches for the instantiation func that 192 works on the specified \a archive. Use instantiate_object() instead. 193*/ 194 195 196//! @} 197