00001 /* +---------------------------------------------------------------------------+ 00002 | The Mobile Robot Programming Toolkit (MRPT) C++ library | 00003 | | 00004 | http://www.mrpt.org/ | 00005 | | 00006 | Copyright (C) 2005-2011 University of Malaga | 00007 | | 00008 | This software was written by the Machine Perception and Intelligent | 00009 | Robotics Lab, University of Malaga (Spain). | 00010 | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> | 00011 | | 00012 | This file is part of the MRPT project. | 00013 | | 00014 | MRPT is free software: you can redistribute it and/or modify | 00015 | it under the terms of the GNU General Public License as published by | 00016 | the Free Software Foundation, either version 3 of the License, or | 00017 | (at your option) any later version. | 00018 | | 00019 | MRPT is distributed in the hope that it will be useful, | 00020 | but WITHOUT ANY WARRANTY; without even the implied warranty of | 00021 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | 00022 | GNU General Public License for more details. | 00023 | | 00024 | You should have received a copy of the GNU General Public License | 00025 | along with MRPT. If not, see <http://www.gnu.org/licenses/>. | 00026 | | 00027 +---------------------------------------------------------------------------+ */ 00028 #ifndef CSERIALIZABLE_H 00029 #define CSERIALIZABLE_H 00030 00031 #include <mrpt/utils/CObject.h> 00032 #include <mrpt/utils/CStream.h> 00033 #include <mrpt/utils/safe_pointers.h> 00034 00035 #include <set> 00036 #include <list> 00037 00038 namespace mrpt 00039 { 00040 /** Classes for serialization, sockets, ini-file manipulation, streams, list of properties-values, timewatch, extensions to STL. 00041 * \ingroup mrpt_base_grp 00042 */ 00043 namespace utils 00044 { 00045 DEFINE_MRPT_OBJECT_PRE( CSerializable ) 00046 00047 /** The virtual base class which provides a unified interface for all persistent objects in MRPT. 00048 * Many important properties of this class are inherited from mrpt::utils::CObject. See that class for more details. 00049 * Refer to the tutorial about <a href="http://www.mrpt.org/Serialization" >serialization</a> in the wiki. 00050 * \sa CStream 00051 * \ingroup mrpt_base_grp 00052 */ 00053 class BASE_IMPEXP CSerializable : public mrpt::utils::CObject 00054 { 00055 // This must be added to any CObject derived class: 00056 DEFINE_VIRTUAL_MRPT_OBJECT( CSerializable ) 00057 00058 virtual ~CSerializable() { } 00059 00060 protected: 00061 /** Introduces a pure virtual method responsible for writing to a CStream. 00062 * This can not be used directly be users, instead use "stream << object;" 00063 * for writing it to a stream. 00064 * \param out The output binary stream where object must be dumped. 00065 * \param getVersion If NULL, the object must be dumped. If not, only the 00066 * version of the object dump must be returned in this pointer. This enables 00067 * the versioning of objects dumping and backward compatibility with previously 00068 * stored data. 00069 * \exception std::exception On any error, see CStream::WriteBuffer 00070 * \sa CStream 00071 */ 00072 virtual void writeToStream(mrpt::utils::CStream &out, int *getVersion) const = 0; 00073 00074 /** Introduces a pure virtual method responsible for loading from a CStream 00075 * This can not be used directly be users, instead use "stream >> object;" 00076 * for reading it from a stream or "stream >> object_ptr;" if the class is 00077 * unknown apriori. 00078 * \param in The input binary stream where the object data must read from. 00079 * \param version The version of the object stored in the stream: use this version 00080 * number in your code to know how to read the incoming data. 00081 * \exception std::exception On any error, see CStream::ReadBuffer 00082 * \sa CStream 00083 */ 00084 virtual void readFromStream(mrpt::utils::CStream &in, int version) = 0; 00085 }; // End of class def. 00086 00087 00088 /** @name Non-streaming serialization functions 00089 @{ */ 00090 00091 /** Used to pass MRPT objects into a CORBA-like object (strings). See doc about "Integration with BABEL". 00092 * \param o The object to be serialized. 00093 * \return The string containing the binay version of object. 00094 * \sa StringToObject, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a> 00095 */ 00096 std::string BASE_IMPEXP ObjectToString(const CSerializable *o); 00097 00098 /** Used to pass CORBA-like objects (strings) into a MRPT object. 00099 * \param str An string generated with ObjectToString 00100 * \param obj A currently empty pointer, where a pointer to the newly created object will be stored. 00101 * \exception None On any internal exception, this function returns NULL. 00102 * \sa ObjectToString, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a> 00103 */ 00104 void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj); 00105 00106 /** Converts (serializes) an MRPT object into an array of bytes. 00107 * \param o The object to be serialized. 00108 * \param out_vector The vector which at return will contain the data. Size will be set automatically. 00109 * \sa OctetVectorToObject, ObjectToString 00110 */ 00111 void BASE_IMPEXP ObjectToOctetVector(const CSerializable *o, vector_byte & out_vector); 00112 00113 /** Converts back (de-serializes) a sequence of binary data into a MRPT object, without prior information about the object's class. 00114 * \param in_data The serialized input data representing the object. 00115 * \param obj The newly created object will be stored in this smart pointer. 00116 * \exception None On any internal exception, this function returns a NULL pointer. 00117 * \sa ObjectToOctetVector, StringToObject 00118 */ 00119 void BASE_IMPEXP OctetVectorToObject(const vector_byte & in_data, CSerializablePtr &obj); 00120 00121 /** Converts (serializes) an MRPT object into an array of bytes within a std::string, without codifying to avoid NULL characters. 00122 * This is therefore more efficient than ObjectToString 00123 * \param o The object to be serialized. 00124 * \param out_vector The string which at return will contain the data. Size will be set automatically. 00125 * \sa RawStringToObject, ObjectToOctetVector 00126 */ 00127 void BASE_IMPEXP ObjectToRawString(const CSerializable *o, std::string & out_str); 00128 00129 /** Converts back (de-serializes) a sequence of binary data within a std::string into a MRPT object, without prior information about the object's class. 00130 * \param in_data The serialized input data representing the object. 00131 * \param obj The newly created object will be stored in this smart pointer. 00132 * \exception None On any internal exception, this function returns a NULL pointer. 00133 * \sa ObjectToRawString 00134 */ 00135 void BASE_IMPEXP RawStringToObject(const std::string & in_str, CSerializablePtr &obj); 00136 00137 /** @} */ 00138 00139 00140 00141 /** @name Conversion of type to string at compile time 00142 * IMPORTANT: See also the implementation of Serialization for STL containers in mrpt/utils/stl_extensions.h 00143 @{ */ 00144 00145 /** A template to obtain the type of its argument as a string at compile time. 00146 * It works with all classes derived from CSerializable, plus many specializations for the plain data types (bool, double, uint8_t, etc...) 00147 * For example: 00148 * \code 00149 * cout << TTypeName<double>::get() << endl; // "double" 00150 * cout << TTypeName<CPose2D>::get() << endl; // "CPose2D" 00151 * cout << TTypeName<mrpt::slam::COccupancyGridMap2D>::get() << endl; // "COccupancyGridMap2D" 00152 * \endcode 00153 * 00154 * Users can extend this for custom structs/classes with the macro DECLARE_CUSTOM_TTYPENAME: 00155 * \code 00156 * class MyClass { ... }; 00157 * DECLARE_CUSTOM_TTYPENAME(MyClass) 00158 * cout << TTypeName<MyClass>::get() << endl; // "MyClass" 00159 * \endcode 00160 * 00161 * The following types are NOT ALLOWED since they have platform-dependant sizes: 00162 * - int, unsigned int 00163 * - long, unsigned long 00164 * - short, unsigned short 00165 * - size_t 00166 * 00167 */ 00168 template<typename T> 00169 struct TTypeName 00170 { 00171 static std::string get() { 00172 return std::string( T::classinfo->className ); 00173 } 00174 }; 00175 00176 /** Identical to MRPT_DECLARE_TTYPENAME but intended for user code. 00177 * MUST be placed at the GLOBAL namespace. 00178 */ 00179 #define DECLARE_CUSTOM_TTYPENAME(_TYPE) \ 00180 namespace mrpt { namespace utils { MRPT_DECLARE_TTYPENAME(_TYPE) } } 00181 00182 #define MRPT_DECLARE_TTYPENAME(_TYPE) \ 00183 template<> struct TTypeName <_TYPE > { \ 00184 static std::string get() { return std::string(#_TYPE); } }; 00185 00186 #define MRPT_DECLARE_TTYPENAME_PTR(_TYPE) \ 00187 template<> struct TTypeName <_TYPE##Ptr> { \ 00188 static std::string get() { return TTypeName<_TYPE>::get(); } }; 00189 00190 MRPT_DECLARE_TTYPENAME(bool) 00191 MRPT_DECLARE_TTYPENAME(double) 00192 MRPT_DECLARE_TTYPENAME(float) 00193 MRPT_DECLARE_TTYPENAME(uint64_t) 00194 MRPT_DECLARE_TTYPENAME(int64_t) 00195 MRPT_DECLARE_TTYPENAME(uint32_t) 00196 MRPT_DECLARE_TTYPENAME(int32_t) 00197 MRPT_DECLARE_TTYPENAME(uint16_t) 00198 MRPT_DECLARE_TTYPENAME(int16_t) 00199 MRPT_DECLARE_TTYPENAME(uint8_t) 00200 MRPT_DECLARE_TTYPENAME(int8_t) 00201 00202 MRPT_DECLARE_TTYPENAME(std::string) 00203 00204 00205 #define MRPT_DECLARE_TTYPENAME_CONTAINER(_CONTAINER) \ 00206 template< typename V > \ 00207 struct TTypeName <_CONTAINER<V> > { \ 00208 static std::string get() { \ 00209 return std::string( #_CONTAINER )+std::string("<")+std::string( TTypeName<V>::get() ) + std::string(">"); \ 00210 } \ 00211 }; 00212 00213 MRPT_DECLARE_TTYPENAME_CONTAINER( std::vector ) 00214 MRPT_DECLARE_TTYPENAME_CONTAINER( std::deque ) 00215 MRPT_DECLARE_TTYPENAME_CONTAINER( std::list ) 00216 MRPT_DECLARE_TTYPENAME_CONTAINER( std::set ) 00217 00218 // These ones act as a "translation" between vector_XXX types and their base classes: 00219 #define MRPT_DECLARE_TTYPENAME_MAP_FOR_VECTOR(_CONT) \ 00220 template<> struct TTypeName <_CONT> : TTypeName<std::vector<_CONT::Scalar> > { }; 00221 00222 MRPT_DECLARE_TTYPENAME_MAP_FOR_VECTOR(vector_float) 00223 MRPT_DECLARE_TTYPENAME_MAP_FOR_VECTOR(vector_double) 00224 00225 // These ones are not needed since typedef's of "std::vector<>" are automatically supported 00226 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_signed_byte ) 00227 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_signed_word) 00228 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_int) 00229 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_long) 00230 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_byte) 00231 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_word) 00232 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_uint) 00233 //#if MRPT_WORD_SIZE!=32 // If it's 32 bit, size_t <=> uint32_t 00234 //MRPT_DECLARE_TTYPENAME_MAP_FOR_STDVECTOR(vector_size_t) 00235 //#endif 00236 00237 00238 #define MRPT_DECLARE_TTYPENAME_CONTAINER_ASSOC(_CONTAINER) \ 00239 template< typename K, typename V > \ 00240 struct TTypeName <_CONTAINER<K,V> > { \ 00241 static std::string get() { \ 00242 return std::string( #_CONTAINER )+std::string("<")+std::string( TTypeName<K>::get() )+ std::string(",")+std::string( TTypeName<V>::get() )+std::string(">"); \ 00243 } \ 00244 }; 00245 00246 MRPT_DECLARE_TTYPENAME_CONTAINER_ASSOC( std::map ) 00247 MRPT_DECLARE_TTYPENAME_CONTAINER_ASSOC( std::multimap ) 00248 00249 00250 template< typename T1, typename T2 > 00251 struct TTypeName <std::pair<T1,T2> > { 00252 static std::string get() { 00253 return std::string("std::pair<")+std::string( TTypeName<T1>::get() )+ std::string(",")+std::string( TTypeName<T2>::get() )+std::string(">"); 00254 } 00255 }; 00256 00257 /** @} */ 00258 00259 00260 /** This declaration must be inserted in all CSerializable classes definition, within the class declaration. 00261 */ 00262 #define DEFINE_SERIALIZABLE(class_name) \ 00263 DEFINE_MRPT_OBJECT(class_name) \ 00264 protected: \ 00265 /*! @name CSerializable virtual methods */ \ 00266 /*! @{ */ \ 00267 void writeToStream(mrpt::utils::CStream &out, int *getVersion) const;\ 00268 void readFromStream(mrpt::utils::CStream &in, int version); \ 00269 /*! @} */ 00270 00271 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration. 00272 */ 00273 #define DEFINE_SERIALIZABLE_PRE_CUSTOM_LINKAGE(class_name,_LINKAGE_) \ 00274 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, CSerializable, _LINKAGE_ class_name) \ 00275 _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj); 00276 00277 00278 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration. 00279 */ 00280 #define DEFINE_SERIALIZABLE_PRE(class_name) \ 00281 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, CSerializable, BASE_IMPEXP class_name) \ 00282 BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj); 00283 00284 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration. 00285 */ 00286 #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \ 00287 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name) \ 00288 _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj); 00289 00290 00291 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration. 00292 */ 00293 #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE(class_name, base_name) \ 00294 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP ) \ 00295 BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj); 00296 00297 /** This must be inserted in all CSerializable classes implementation files: 00298 */ 00299 #define IMPLEMENTS_SERIALIZABLE(class_name, base,NameSpace) \ 00300 IMPLEMENTS_MRPT_OBJECT(class_name, base,NameSpace) \ 00301 mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, NameSpace::class_name##Ptr &pObj) \ 00302 { pObj = NameSpace::class_name##Ptr( in.ReadObject() ); return in; } 00303 00304 /** This declaration must be inserted in virtual CSerializable classes definition: 00305 */ 00306 #define DEFINE_VIRTUAL_SERIALIZABLE(class_name) \ 00307 DEFINE_VIRTUAL_MRPT_OBJECT(class_name) 00308 00309 /** This must be inserted as implementation of some required members for 00310 * virtual CSerializable classes: 00311 */ 00312 #define IMPLEMENTS_VIRTUAL_SERIALIZABLE(class_name, base_class_name,NameSpace) \ 00313 IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class_name,NameSpace) \ 00314 mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj) \ 00315 { pObj = class_name##Ptr( in.ReadObject() ); return in; } 00316 00317 00318 } // End of namespace 00319 } // End of namespace 00320 00321 #endif
| Page generated by Doxygen 1.7.5 for MRPT 0.9.5 SVN: at Thu Oct 13 21:25:36 UTC 2011 |