Main MRPT website > C++ reference for MRPT 1.5.6
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-2017, 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/TTypeName.h>
15 
16 #if MRPT_HAS_MATLAB
17 typedef struct mxArray_tag mxArray; //!< Forward declaration for mxArray (avoid #including as much as possible to speed up compiling)
18 #endif
19 
20 namespace mrpt
21 {
22  namespace utils {
23  class CStream;
24  }
25 
26  /** Classes for serialization, sockets, ini-file manipulation, streams, list of properties-values, timewatch, extensions to STL.
27  * \ingroup mrpt_base_grp
28  */
29  namespace utils
30  {
31  DEFINE_MRPT_OBJECT_PRE( CSerializable )
32 
33  /** The virtual base class which provides a unified interface for all persistent objects in MRPT.
34  * Many important properties of this class are inherited from mrpt::utils::CObject. See that class for more details.
35  * Refer to the tutorial about <a href="http://www.mrpt.org/Serialization" >serialization</a> online.
36  * \sa CStream
37  * \ingroup mrpt_base_grp
38  */
39  class BASE_IMPEXP CSerializable : public mrpt::utils::CObject
40  {
41  // This must be added to any CObject derived class:
43 
44  virtual ~CSerializable() { }
45 
46  protected:
47  /** Introduces a pure virtual method responsible for writing to a CStream.
48  * This can not be used directly be users, instead use "stream << object;"
49  * for writing it to a stream.
50  * \param out The output binary stream where object must be dumped.
51  * \param getVersion If NULL, the object must be dumped. If not, only the
52  * version of the object dump must be returned in this pointer. This enables
53  * the versioning of objects dumping and backward compatibility with previously
54  * stored data.
55  * \exception std::exception On any error, see CStream::WriteBuffer
56  * \sa CStream
57  */
58  virtual void writeToStream(mrpt::utils::CStream &out, int *getVersion) const = 0;
59 
60  /** Introduces a pure virtual method responsible for loading from a CStream
61  * This can not be used directly be users, instead use "stream >> object;"
62  * for reading it from a stream or "stream >> object_ptr;" if the class is
63  * unknown apriori.
64  * \param in The input binary stream where the object data must read from.
65  * \param version The version of the object stored in the stream: use this version
66  * number in your code to know how to read the incoming data.
67  * \exception std::exception On any error, see CStream::ReadBuffer
68  * \sa CStream
69  */
70  virtual void readFromStream(mrpt::utils::CStream &in, int version) = 0;
71 
72  public:
73 
74  /** Introduces a pure virtual method responsible for writing to a `mxArray` Matlab object,
75  * typically a MATLAB `struct` whose contents are documented in each derived class.
76  * \return A new `mxArray` (caller is responsible of memory freeing) or NULL is class does not support conversion to MATLAB.
77  */
78 #if MRPT_HAS_MATLAB
79  virtual mxArray* writeToMatlab() const { return NULL; }
80 #endif
81  }; // End of class def.
82 
83  DEFINE_MRPT_OBJECT_POST( CSerializable )
84 
85  /** \addtogroup noncstream_serialization Non-CStream serialization functions (in #include <mrpt/utils/CSerializable.h>)
86  * \ingroup mrpt_base_grp
87  * @{ */
88 
89  /** Used to pass MRPT objects into a CORBA-like object (strings). See doc about "Integration with BABEL".
90  * \param o The object to be serialized.
91  * \return The string containing the binay version of object.
92  * \sa StringToObject, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
93  */
94  std::string BASE_IMPEXP ObjectToString(const CSerializable *o);
95 
96  /** Used to pass CORBA-like objects (strings) into a MRPT object.
97  * \param str An string generated with ObjectToString
98  * \param obj A currently empty pointer, where a pointer to the newly created object will be stored.
99  * \exception None On any internal exception, this function returns NULL.
100  * \sa ObjectToString, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
101  */
102  void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj);
103 
104  /** Converts (serializes) an MRPT object into an array of bytes.
105  * \param o The object to be serialized.
106  * \param out_vector The vector which at return will contain the data. Size will be set automatically.
107  * \sa OctetVectorToObject, ObjectToString
108  */
109  void BASE_IMPEXP ObjectToOctetVector(const CSerializable *o, vector_byte & out_vector);
110 
111  /** Converts back (de-serializes) a sequence of binary data into a MRPT object, without prior information about the object's class.
112  * \param in_data The serialized input data representing the object.
113  * \param obj The newly created object will be stored in this smart pointer.
114  * \exception None On any internal exception, this function returns a NULL pointer.
115  * \sa ObjectToOctetVector, StringToObject
116  */
117  void BASE_IMPEXP OctetVectorToObject(const vector_byte & in_data, CSerializablePtr &obj);
118 
119  /** Converts (serializes) an MRPT object into an array of bytes within a std::string, without codifying to avoid NULL characters.
120  * This is therefore more efficient than ObjectToString
121  * \param o The object to be serialized.
122  * \param out_vector The string which at return will contain the data. Size will be set automatically.
123  * \sa RawStringToObject, ObjectToOctetVector
124  */
125  void BASE_IMPEXP ObjectToRawString(const CSerializable *o, std::string & out_str);
126 
127  /** 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.
128  * \param in_data The serialized input data representing the object.
129  * \param obj The newly created object will be stored in this smart pointer.
130  * \exception None On any internal exception, this function returns a NULL pointer.
131  * \sa ObjectToRawString
132  */
133  void BASE_IMPEXP RawStringToObject(const std::string & in_str, CSerializablePtr &obj);
134 
135  /** @} */
136 
137  /** Like DEFINE_SERIALIZABLE, but for template classes that need the DLL imp/exp keyword in Windows. */
138  #define DEFINE_SERIALIZABLE_CUSTOM_LINKAGE(class_name, _VOID_LINKAGE_, _STATIC_LINKAGE_, _VIRTUAL_LINKAGE_ ) \
139  DEFINE_MRPT_OBJECT_CUSTOM_LINKAGE(class_name, _STATIC_LINKAGE_, _VIRTUAL_LINKAGE_ ) \
140  protected: \
141  /*! @name CSerializable virtual methods */ \
142  /*! @{ */ \
143  _VOID_LINKAGE_ writeToStream(mrpt::utils::CStream &out, int *getVersion) const MRPT_OVERRIDE;\
144  _VOID_LINKAGE_ readFromStream(mrpt::utils::CStream &in, int version) MRPT_OVERRIDE; \
145  /*! @} */
146 
147  /** This declaration must be inserted in all CSerializable classes definition, within the class declaration. */
148  #define DEFINE_SERIALIZABLE(class_name) \
149  DEFINE_SERIALIZABLE_CUSTOM_LINKAGE(class_name, void /*no extra linkage keyword*/, static /*none*/,virtual /*none*/ )
150 
151  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
152  */
153  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_LINKAGE(class_name,_LINKAGE_) \
154  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, _LINKAGE_ class_name) \
155  _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
156 
157  #define DEFINE_SERIALIZABLE_POST_CUSTOM_LINKAGE(class_name,_LINKAGE_) \
158  DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, _LINKAGE_ class_name)
159 
160  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
161  */
162  #define DEFINE_SERIALIZABLE_PRE(class_name) \
163  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, BASE_IMPEXP class_name) \
164  BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
165 
166  #define DEFINE_SERIALIZABLE_POST(class_name) \
167  DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, BASE_IMPEXP class_name)
168 
169  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
170  */
171  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \
172  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name) \
173  _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
174 
175  #define DEFINE_SERIALIZABLE_POST_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \
176  DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name)
177 
178  /** This declaration must be inserted in all CSerializable classes definition, before the class declaration. */
179  #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE(class_name, base_name) \
180  DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP ) \
181  BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
182 
183  #define DEFINE_SERIALIZABLE_POST_CUSTOM_BASE(class_name, base_name) \
184  DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP ) \
185 
186  /** This must be inserted in all CSerializable classes implementation files */
187  #define IMPLEMENTS_SERIALIZABLE(class_name, base,NameSpace) \
188  IMPLEMENTS_MRPT_OBJECT(class_name, base,NameSpace) \
189  mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, NameSpace::class_name##Ptr &pObj) \
190  { pObj = NameSpace::class_name##Ptr( in.ReadObject() ); return in; }
191 
192  /** This declaration must be inserted in virtual CSerializable classes definition: */
193  #define DEFINE_VIRTUAL_SERIALIZABLE(class_name) \
194  DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
195 
196  /** This must be inserted as implementation of some required members for
197  * virtual CSerializable classes:
198  */
199  #define IMPLEMENTS_VIRTUAL_SERIALIZABLE(class_name, base_class_name,NameSpace) \
200  IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class_name,NameSpace) \
201  mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj) \
202  { pObj = class_name##Ptr( in.ReadObject() ); return in; }
203 
204  /** This must be inserted if a custom conversion method for MEX API is implemented in the class */
205  #if MRPT_HAS_MATLAB
206  #define DECLARE_MEX_CONVERSION \
207  /*! @name Virtual methods for MRPT-MEX conversion */ \
208  /*! @{ */ \
209  public: \
210  virtual mxArray* writeToMatlab() const; \
211  /*! @} */
212  #else
213  #define DECLARE_MEX_CONVERSION //Empty
214  #endif
215 
216  /** This must be inserted if a custom conversion method for MEX API is implemented in the class */
217  #if MRPT_HAS_MATLAB
218  #define DECLARE_MEXPLUS_FROM( complete_type ) \
219  namespace mexplus \
220  { \
221  template <typename T> \
222  mxArray* from(const T& value); \
223  template <> \
224  mxArray* from(const complete_type& value); \
225  }
226 
227  #define IMPLEMENTS_MEXPLUS_FROM( complete_type ) \
228  namespace mexplus \
229  { \
230  template <> \
231  mxArray* from(const complete_type& var) \
232  { \
233  return var.writeToMatlab(); \
234  } \
235  }
236  #else
237  #define DECLARE_MEXPLUS_FROM(complete_type) //Empty
238  #define IMPLEMENTS_MEXPLUS_FROM(complete_type) //Empty
239  #endif
240 
241  } // End of namespace
242 } // End of namespace
243 
244 #endif
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...
std::vector< uint8_t > vector_byte
Definition: types_simple.h:26
The virtual base class which provides a unified interface for all persistent objects in MRPT...
Definition: CSerializable.h:39
#define DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
This declaration must be inserted in virtual CSerializable classes definition:
Definition: CObject.h:275
#define DEFINE_MRPT_OBJECT_POST(class_name)
Definition: CObject.h:252
GLsizei GLsizei GLuint * obj
Definition: glext.h:3902
This base class is used to provide a unified interface to files,memory buffers,..Please see the deriv...
Definition: CStream.h:38
void BASE_IMPEXP ObjectToOctetVector(const CSerializable *o, vector_byte &out_vector)
Converts (serializes) an MRPT object into an array of bytes.
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...
int version
Definition: mrpt_jpeglib.h:898
GLsizei const GLchar ** string
Definition: glext.h:3919
#define DEFINE_MRPT_OBJECT_PRE(class_name)
This declaration must be inserted in all CObject classes definition, before the class declaration...
Definition: CObject.h:251
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
virtual mxArray * writeToMatlab() const
Introduces a pure virtual method responsible for writing to a mxArray Matlab object, typically a MATLAB struct whose contents are documented in each derived class.
Definition: CSerializable.h:79
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...
std::string BASE_IMPEXP ObjectToString(const CSerializable *o)
Used to pass MRPT objects into a CORBA-like object (strings).
GLuint in
Definition: glext.h:6301
The virtual base class of all MRPT classes with a unified RTTI system.
Definition: CObject.h:123
void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj)
Used to pass CORBA-like objects (strings) into a MRPT object.
struct mxArray_tag mxArray
Forward declaration for mxArray (avoid #including as much as possible to speed up compiling) ...
Definition: CSerializable.h:17



Page generated by Doxygen 1.8.14 for MRPT 1.5.6 Git: 4c65e8431 Tue Apr 24 08:18:17 2018 +0200 at lun oct 28 01:35:26 CET 2019