Main MRPT website > C++ reference
MRPT logo
CSerializable.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | http://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2014, Individual contributors, see AUTHORS file |
6  | See: http://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See details in http://www.mrpt.org/License |
8  +---------------------------------------------------------------------------+ */
9 #ifndef CSERIALIZABLE_H
10 #define CSERIALIZABLE_H
11 
12 #include <mrpt/utils/CObject.h>
13 #include <mrpt/utils/CStream.h>
15 #include <mrpt/utils/TTypeName.h>
16 
17 namespace mrpt
18 {
19  /** Classes for serialization, sockets, ini-file manipulation, streams, list of properties-values, timewatch, extensions to STL.
20  * \ingroup mrpt_base_grp
21  */
22  namespace utils
23  {
25 
26  /** The virtual base class which provides a unified interface for all persistent objects in MRPT.
27  * Many important properties of this class are inherited from mrpt::utils::CObject. See that class for more details.
28  * Refer to the tutorial about <a href="http://www.mrpt.org/Serialization" >serialization</a> online.
29  * \sa CStream
30  * \ingroup mrpt_base_grp
31  */
32  class BASE_IMPEXP CSerializable : public mrpt::utils::CObject
33  {
34  // This must be added to any CObject derived class:
36 
37  virtual ~CSerializable() { }
38 
39  protected:
40  /** Introduces a pure virtual method responsible for writing to a CStream.
41  * This can not be used directly be users, instead use "stream << object;"
42  * for writing it to a stream.
43  * \param out The output binary stream where object must be dumped.
44  * \param getVersion If NULL, the object must be dumped. If not, only the
45  * version of the object dump must be returned in this pointer. This enables
46  * the versioning of objects dumping and backward compatibility with previously
47  * stored data.
48  * \exception std::exception On any error, see CStream::WriteBuffer
49  * \sa CStream
50  */
51  virtual void writeToStream(mrpt::utils::CStream &out, int *getVersion) const = 0;
52 
53  /** Introduces a pure virtual method responsible for loading from a CStream
54  * This can not be used directly be users, instead use "stream >> object;"
55  * for reading it from a stream or "stream >> object_ptr;" if the class is
56  * unknown apriori.
57  * \param in The input binary stream where the object data must read from.
58  * \param version The version of the object stored in the stream: use this version
59  * number in your code to know how to read the incoming data.
60  * \exception std::exception On any error, see CStream::ReadBuffer
61  * \sa CStream
62  */
63  virtual void readFromStream(mrpt::utils::CStream &in, int version) = 0;
64  }; // End of class def.
65 
66 
67  /** @name Non-streaming serialization functions
68  @{ */
69 
70  /** Used to pass MRPT objects into a CORBA-like object (strings). See doc about "Integration with BABEL".
71  * \param o The object to be serialized.
72  * \return The string containing the binay version of object.
73  * \sa StringToObject, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
74  */
75  std::string BASE_IMPEXP ObjectToString(const CSerializable *o);
76 
77  /** Used to pass CORBA-like objects (strings) into a MRPT object.
78  * \param str An string generated with ObjectToString
79  * \param obj A currently empty pointer, where a pointer to the newly created object will be stored.
80  * \exception None On any internal exception, this function returns NULL.
81  * \sa ObjectToString, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
82  */
83  void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj);
84 
85  /** Converts (serializes) an MRPT object into an array of bytes.
86  * \param o The object to be serialized.
87  * \param out_vector The vector which at return will contain the data. Size will be set automatically.
88  * \sa OctetVectorToObject, ObjectToString
89  */
90  void BASE_IMPEXP ObjectToOctetVector(const CSerializable *o, vector_byte & out_vector);
91 
92  /** Converts back (de-serializes) a sequence of binary data into a MRPT object, without prior information about the object's class.
93  * \param in_data The serialized input data representing the object.
94  * \param obj The newly created object will be stored in this smart pointer.
95  * \exception None On any internal exception, this function returns a NULL pointer.
96  * \sa ObjectToOctetVector, StringToObject
97  */
98  void BASE_IMPEXP OctetVectorToObject(const vector_byte & in_data, CSerializablePtr &obj);
99 
100  /** Converts (serializes) an MRPT object into an array of bytes within a std::string, without codifying to avoid NULL characters.
101  * This is therefore more efficient than ObjectToString
102  * \param o The object to be serialized.
103  * \param out_vector The string which at return will contain the data. Size will be set automatically.
104  * \sa RawStringToObject, ObjectToOctetVector
105  */
106  void BASE_IMPEXP ObjectToRawString(const CSerializable *o, std::string & out_str);
107 
108  /** 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.
109  * \param in_data The serialized input data representing the object.
110  * \param obj The newly created object will be stored in this smart pointer.
111  * \exception None On any internal exception, this function returns a NULL pointer.
112  * \sa ObjectToRawString
113  */
114  void BASE_IMPEXP RawStringToObject(const std::string & in_str, CSerializablePtr &obj);
115 
116  /** @} */
117 
118  /** Like DEFINE_SERIALIZABLE, but for template classes that need the DLL imp/exp keyword in Windows. */
119  #define DEFINE_SERIALIZABLE_CUSTOM_LINKAGE(class_name, _VOID_LINKAGE_, _STATIC_LINKAGE_, _VIRTUAL_LINKAGE_ ) \
120  DEFINE_MRPT_OBJECT_CUSTOM_LINKAGE(class_name, _STATIC_LINKAGE_, _VIRTUAL_LINKAGE_ ) \
121  protected: \
122  /*! @name CSerializable virtual methods */ \
123  /*! @{ */ \
124  _VOID_LINKAGE_ writeToStream(mrpt::utils::CStream &out, int *getVersion) const;\
125  _VOID_LINKAGE_ readFromStream(mrpt::utils::CStream &in, int version); \
126  /*! @} */
127 
128  /** This declaration must be inserted in all CSerializable classes definition, within the class declaration. */
129  #define DEFINE_SERIALIZABLE(class_name) \
130  DEFINE_SERIALIZABLE_CUSTOM_LINKAGE(class_name, void /*no extra linkage keyword*/, static /*none*/,virtual /*none*/ )
131 
132  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
133  */
134  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_LINKAGE(class_name,_LINKAGE_) \
135  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, CSerializable, _LINKAGE_ class_name) \
136  _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
137 
138 
139  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
140  */
141  #define DEFINE_SERIALIZABLE_PRE(class_name) \
142  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, CSerializable, BASE_IMPEXP class_name) \
143  BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
144 
145  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
146  */
147  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \
148  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name) \
149  _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
150 
151 
152  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
153  */
154  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE(class_name, base_name) \
155  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP ) \
156  BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
157 
158  /** This must be inserted in all CSerializable classes implementation files:
159  */
160  #define IMPLEMENTS_SERIALIZABLE(class_name, base,NameSpace) \
161  IMPLEMENTS_MRPT_OBJECT(class_name, base,NameSpace) \
162  mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, NameSpace::class_name##Ptr &pObj) \
163  { pObj = NameSpace::class_name##Ptr( in.ReadObject() ); return in; }
164 
165  /** This declaration must be inserted in virtual CSerializable classes definition:
166  */
167  #define DEFINE_VIRTUAL_SERIALIZABLE(class_name) \
168  DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
169 
170  /** This must be inserted as implementation of some required members for
171  * virtual CSerializable classes:
172  */
173  #define IMPLEMENTS_VIRTUAL_SERIALIZABLE(class_name, base_class_name,NameSpace) \
174  IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class_name,NameSpace) \
175  mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj) \
176  { pObj = class_name##Ptr( in.ReadObject() ); return in; }
177 
178  } // End of namespace
179 } // End of namespace
180 
181 #endif
The virtual base class which provides a unified interface for all persistent objects in MRPT...
Definition: CSerializable.h:32
#define DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
This declaration must be inserted in virtual CSerializable classes definition:
Definition: CObject.h:258
This base class is used to provide a unified interface to files,memory buffers,..Please see the deriv...
Definition: CStream.h:36
class BASE_IMPEXP CSerializable
Definition: CStream.h:21
void BASE_IMPEXP ObjectToOctetVector(const CSerializable *o, vector_byte &out_vector)
Converts (serializes) an MRPT object into an array of bytes.
std::vector< uint8_t > vector_byte
struct BASE_IMPEXP CSerializablePtr
Definition: CStream.h:22
#define DEFINE_MRPT_OBJECT_PRE(class_name)
This declaration must be inserted in all CObject classes definition, before the class declaration...
Definition: CObject.h:234
std::string BASE_IMPEXP ObjectToString(const CSerializable *o)
Used to pass MRPT objects into a CORBA-like object (strings).
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
void BASE_IMPEXP OctetVectorToObject(const vector_byte &in_data, CSerializablePtr &obj)
Converts back (de-serializes) a sequence of binary data into a MRPT object, without prior information...
void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj)
Used to pass CORBA-like objects (strings) into a MRPT object.
void BASE_IMPEXP ObjectToRawString(const CSerializable *o, std::string &out_str)
Converts (serializes) an MRPT object into an array of bytes within a std::string, without codifying t...
The virtual base class of all MRPT classes with a unified RTTI system.
Definition: CObject.h:115
void BASE_IMPEXP RawStringToObject(const std::string &in_str, CSerializablePtr &obj)
Converts back (de-serializes) a sequence of binary data within a std::string into a MRPT object...



Page generated by Doxygen 1.8.14 for MRPT 1.1.0 SVN: at lun oct 28 00:54:49 CET 2019 Hosted on:
SourceForge.net Logo