1/* 2 * Copyright 2007, Haiku, Inc. All Rights Reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Documentation by: 6 * Niels Sascha Reedijk <niels.reedijk@gmail.com> 7 * Corresponds to: 8 * /trunk/headers/os/support/Archivable.h rev 19972 9 * /trunk/src/kits/support/Archivable.cpp rev 19095 10 */ 11 12/*! 13 \file Archivable.h 14 \brief Provides the BArchivable interface. 15*/ 16 17/*! 18 \class BArchivable 19 \ingroup support 20 \ingroup libbe 21 \brief Interfaced for objects that can be archived into a BMessage. 22 23 BArchivable provides an interface for objects that can be archived into 24 messages and unarchived to objects in another location. By these means you 25 are able to send objects between applications, or even between computers over 26 networks. 27 28 BArchivable differs from BFlattenable in way that BFlattenable is designed to 29 store objects to flat streams of data, where the main objective is storing it 30 to disk. The objective of this interface is to archive objects that will be 31 restored as objects. To illustrate that point, BArchivable messages know how 32 to restore itself, whereas BFlattenables have a datatype which you manually 33 need to map to classes. 34 35 Archiving is done with the Archive() method. If your class support it, the 36 caller can request your class to to a deep archivation, which means that all 37 child objects should be stored. Unarchiving works with the Instantiate() 38 method, which is static. However, since the interface is designed to 39 unarchive objects without the caller knowing what kind of object it 40 actually is, the global function #instantiate_object() instantiates a message 41 without you manually having to determine the class the message is from. This 42 adds considerable flexibility and allows BArchivable to be used in 43 combination with add-ons. 44 45 To provide this interface in your classes, you should publicly inherit this 46 class. You should reimplement Archive() and Instantiate(), and provide one 47 constructor that takes one BMessage argument. 48*/ 49 50/*! 51 \fn BArchivable::BArchivable(BMessage* from) 52 \brief Constructor. Does nothing. 53 54 If you inherit this interface, you should at least provide one constructor 55 that takes one BMessage argument. 56*/ 57 58/*! 59 \fn BArchivable::BArchivable() 60 \brief Constructor. Does nothing. 61*/ 62 63/*! 64 \fn BArchivable::~BArchivable() 65 \brief Destructor. Does nothing. 66*/ 67 68/*! 69 \fn virtual status_t BArchivable::Archive(BMessage* into, bool deep = true) const 70 \brief Archive the object into a BMessage. 71 72 You should call this method from your derived implementation, as it finishes 73 the message to contain data to instantiate your object. 74 75 \param into The message you may store your object in. 76 \param deep If \c true, all child object of this object should be stored as 77 well. Naturally, only pay attention of this parameter if you actually have 78 child objects. 79 \retval B_OK The archiving succeeded. 80 \retval "error codes" The archiving did not succeed. 81*/ 82 83/*! 84 \fn static BArchivable* BArchivable::Instantiate(BMessage* archive) 85 \brief Static member to restore objects from messages. 86 87 You should always check that the \a archive argument actually corresponds to 88 your class. The automatic functions, such as #instantiate_object() will not 89 choose the wrong class, but some manual calls to this member might be faulty. 90 91 \param archive The message with the data to restore an object. 92 \retval You should return a pointer to your object, or \c NULL if you 93 failed to succeed. 94 \warning The default implementation will always return \c NULL. Even though 95 it is possible to store plain BArchive objects, it is impossible to restore 96 them. 97 \see instantiate_object(BMessage *from) 98*/ 99 100/*! 101 \fn virtual status_t BArchivable::Perform(perform_code d, void* arg) 102 \brief Internal method. 103 \internal This method is used to extend the API or to provide 'hidden' 104 features. Currently nothing of interest is implemented. 105*/ 106 107///////////////////// Global methods 108/*! 109 \addtogroup support_globals 110 @{ 111*/ 112 113/*! 114 \typedef typedef BArchivable* (*instantiation_func)(BMessage*) 115 \brief Internal definition of a function that can instantiate objects that 116 have been created with the BArchivable API. 117*/ 118 119/*! 120 \fn BArchivable* instantiate_object(BMessage *from, image_id *id) 121 \brief Instantiate an archived object with the object being defined in a 122 different application or library. 123 124 This function is similar to instantiate_object(BMessage *from), except that 125 it takes the \a id argument that refers to an image where the object might 126 come from. 127 128 \note Images are names for executable files. Image ids refer to these 129 executable files that have been loaded by your application. Have a look 130 at the kernel API. 131*/ 132 133/*! 134 \fn BArchivable* instantiate_object(BMessage *from) 135 \brief Instantiate an archived object. 136 137 This global function will determine the base class based on the \a from 138 argument, and it will call the Instantiate() function of that object to 139 restore it. 140 141 \param from The archived object. 142 \return The object returns a pointer to the instantiated object, or \c NULL 143 if the instantiation failed. The global \c errno variable will contain the 144 reason it failed. 145 \see instantiate_object(BMessage *from, image_id *id) 146*/ 147 148/*! 149 \fn bool validate_instantiation(BMessage* from, const char* className) 150 \brief Internal function that checks if the \a className is the same as the 151 one stored in the \a from message. 152*/ 153 154/*! 155 \fn instantiation_func find_instantiation_func(const char* className, const char* signature) 156 \brief Internal function that searches for the instantiation func with a 157 specific signature. Use instantiate_object() instead. 158*/ 159 160/*! 161 \fn instantiation_func find_instantiation_func(const char* className) 162 \brief Internal function that searches for the instantiation func of a 163 specific class. Use instantiate_object() instead. 164*/ 165 166/*! 167 \fn instantiation_func find_instantiation_func(BMessage* archive) 168 \brief Internal function that searches for the instantiation func that 169 works on the specified \a archive. Use instantiate_object() instead. 170*/ 171 172//! @} 173