Main MRPT website > C++ reference for MRPT 1.4.0
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-2016, 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>
15
16#if MRPT_HAS_MATLAB
17typedef struct mxArray_tag mxArray; //!< Forward declaration for mxArray (avoid #including as much as possible to speed up compiling)
18#endif
19
20namespace 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 /** @name Non-streaming serialization functions
86 @{ */
87
88 /** Used to pass MRPT objects into a CORBA-like object (strings). See doc about "Integration with BABEL".
89 * \param o The object to be serialized.
90 * \return The string containing the binay version of object.
91 * \sa StringToObject, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
92 */
94
95 /** Used to pass CORBA-like objects (strings) into a MRPT object.
96 * \param str An string generated with ObjectToString
97 * \param obj A currently empty pointer, where a pointer to the newly created object will be stored.
98 * \exception None On any internal exception, this function returns NULL.
99 * \sa ObjectToString, <a href="http://www.mrpt.org/Integration_with_BABEL" >Integration with BABEL</a>
100 */
101 void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj);
102
103 /** Converts (serializes) an MRPT object into an array of bytes.
104 * \param o The object to be serialized.
105 * \param out_vector The vector which at return will contain the data. Size will be set automatically.
106 * \sa OctetVectorToObject, ObjectToString
107 */
109
110 /** Converts back (de-serializes) a sequence of binary data into a MRPT object, without prior information about the object's class.
111 * \param in_data The serialized input data representing the object.
112 * \param obj The newly created object will be stored in this smart pointer.
113 * \exception None On any internal exception, this function returns a NULL pointer.
114 * \sa ObjectToOctetVector, StringToObject
115 */
116 void BASE_IMPEXP OctetVectorToObject(const vector_byte & in_data, CSerializablePtr &obj);
117
118 /** Converts (serializes) an MRPT object into an array of bytes within a std::string, without codifying to avoid NULL characters.
119 * This is therefore more efficient than ObjectToString
120 * \param o The object to be serialized.
121 * \param out_vector The string which at return will contain the data. Size will be set automatically.
122 * \sa RawStringToObject, ObjectToOctetVector
123 */
124 void BASE_IMPEXP ObjectToRawString(const CSerializable *o, std::string & out_str);
125
126 /** 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.
127 * \param in_data The serialized input data representing the object.
128 * \param obj The newly created object will be stored in this smart pointer.
129 * \exception None On any internal exception, this function returns a NULL pointer.
130 * \sa ObjectToRawString
131 */
132 void BASE_IMPEXP RawStringToObject(const std::string & in_str, CSerializablePtr &obj);
133
134 /** @} */
135
136 /** Like DEFINE_SERIALIZABLE, but for template classes that need the DLL imp/exp keyword in Windows. */
137 #define DEFINE_SERIALIZABLE_CUSTOM_LINKAGE(class_name, _VOID_LINKAGE_, _STATIC_LINKAGE_, _VIRTUAL_LINKAGE_ ) \
138 DEFINE_MRPT_OBJECT_CUSTOM_LINKAGE(class_name, _STATIC_LINKAGE_, _VIRTUAL_LINKAGE_ ) \
139 protected: \
140 /*! @name CSerializable virtual methods */ \
141 /*! @{ */ \
142 _VOID_LINKAGE_ writeToStream(mrpt::utils::CStream &out, int *getVersion) const MRPT_OVERRIDE;\
143 _VOID_LINKAGE_ readFromStream(mrpt::utils::CStream &in, int version) MRPT_OVERRIDE; \
144 /*! @} */
145
146 /** This declaration must be inserted in all CSerializable classes definition, within the class declaration. */
147 #define DEFINE_SERIALIZABLE(class_name) \
148 DEFINE_SERIALIZABLE_CUSTOM_LINKAGE(class_name, void /*no extra linkage keyword*/, static /*none*/,virtual /*none*/ )
149
150 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
151 */
152 #define DEFINE_SERIALIZABLE_PRE_CUSTOM_LINKAGE(class_name,_LINKAGE_) \
153 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, _LINKAGE_ class_name) \
154 _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
155
156 #define DEFINE_SERIALIZABLE_POST_CUSTOM_LINKAGE(class_name,_LINKAGE_) \
157 DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, _LINKAGE_ class_name)
158
159 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
160 */
161 #define DEFINE_SERIALIZABLE_PRE(class_name) \
162 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, BASE_IMPEXP class_name) \
163 BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
164
165 #define DEFINE_SERIALIZABLE_POST(class_name) \
166 DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE2(class_name, mrpt::utils::CSerializable, BASE_IMPEXP class_name)
167
168 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration.
169 */
170 #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \
171 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name) \
172 _LINKAGE_ ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
173
174 #define DEFINE_SERIALIZABLE_POST_CUSTOM_BASE_LINKAGE(class_name, base_name, _LINKAGE_ ) \
175 DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE2(class_name, base_name, _LINKAGE_ class_name)
176
177 /** This declaration must be inserted in all CSerializable classes definition, before the class declaration. */
178 #define DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE(class_name, base_name) \
179 DEFINE_MRPT_OBJECT_PRE_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP ) \
180 BASE_IMPEXP ::mrpt::utils::CStream& operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj);
181
182 #define DEFINE_SERIALIZABLE_POST_CUSTOM_BASE(class_name, base_name) \
183 DEFINE_MRPT_OBJECT_POST_CUSTOM_BASE_LINKAGE(class_name, base_name, BASE_IMPEXP ) \
184
185 /** This must be inserted in all CSerializable classes implementation files */
186 #define IMPLEMENTS_SERIALIZABLE(class_name, base,NameSpace) \
187 IMPLEMENTS_MRPT_OBJECT(class_name, base,NameSpace) \
188 mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, NameSpace::class_name##Ptr &pObj) \
189 { pObj = NameSpace::class_name##Ptr( in.ReadObject() ); return in; }
190
191 /** This declaration must be inserted in virtual CSerializable classes definition: */
192 #define DEFINE_VIRTUAL_SERIALIZABLE(class_name) \
193 DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
194
195 /** This must be inserted as implementation of some required members for
196 * virtual CSerializable classes:
197 */
198 #define IMPLEMENTS_VIRTUAL_SERIALIZABLE(class_name, base_class_name,NameSpace) \
199 IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class_name,NameSpace) \
200 mrpt::utils::CStream& NameSpace::operator>>(mrpt::utils::CStream& in, class_name##Ptr &pObj) \
201 { pObj = class_name##Ptr( in.ReadObject() ); return in; }
202
203 /** This must be inserted if a custom conversion method for MEX API is implemented in the class */
204 #if MRPT_HAS_MATLAB
205 #define DECLARE_MEX_CONVERSION \
206 /*! @name Virtual methods for MRPT-MEX conversion */ \
207 /*! @{ */ \
208 public: \
209 virtual mxArray* writeToMatlab() const; \
210 /*! @} */
211 #else
212 #define DECLARE_MEX_CONVERSION //Empty
213 #endif
214
215 /** This must be inserted if a custom conversion method for MEX API is implemented in the class */
216 #if MRPT_HAS_MATLAB
217 #define DECLARE_MEXPLUS_FROM( complete_type ) \
218 namespace mexplus \
219 { \
220 template <typename T> \
221 mxArray* from(const T& value); \
222 template <> \
223 mxArray* from(const complete_type& value); \
224 }
225
226 #define IMPLEMENTS_MEXPLUS_FROM( complete_type ) \
227 namespace mexplus \
228 { \
229 template <> \
230 mxArray* from(const complete_type& var) \
231 { \
232 return var.writeToMatlab(); \
233 } \
234 }
235 #else
236 #define DECLARE_MEXPLUS_FROM(complete_type) //Empty
237 #define IMPLEMENTS_MEXPLUS_FROM(complete_type) //Empty
238 #endif
239
240 } // End of namespace
241} // End of namespace
242
243#endif
#define DEFINE_MRPT_OBJECT_POST(class_name)
Definition: CObject.h:245
#define DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
This declaration must be inserted in virtual CSerializable classes definition:
Definition: CObject.h:268
#define DEFINE_MRPT_OBJECT_PRE(class_name)
This declaration must be inserted in all CObject classes definition, before the class declaration.
Definition: CObject.h:244
struct mxArray_tag mxArray
Forward declaration for mxArray (avoid #including as much as possible to speed up compiling)
Definition: CSerializable.h:17
The virtual base class of all MRPT classes with a unified RTTI system.
Definition: CObject.h:120
The virtual base class which provides a unified interface for all persistent objects in MRPT.
Definition: CSerializable.h:40
virtual mxArray * writeToMatlab() const
Introduces a pure virtual method responsible for writing to a mxArray Matlab object,...
Definition: CSerializable.h:79
virtual void writeToStream(mrpt::utils::CStream &out, int *getVersion) const =0
Introduces a pure virtual method responsible for writing to a CStream.
virtual void readFromStream(mrpt::utils::CStream &in, int version)=0
Introduces a pure virtual method responsible for loading from a CStream This can not be used directly...
This base class is used to provide a unified interface to files,memory buffers,..Please see the deriv...
Definition: CStream.h:39
std::vector< uint8_t > vector_byte
Definition: types_simple.h:26
std::string BASE_IMPEXP ObjectToString(const CSerializable *o)
Used to pass MRPT objects into a CORBA-like object (strings).
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,...
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 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...
void BASE_IMPEXP StringToObject(const std::string &str, CSerializablePtr &obj)
Used to pass CORBA-like objects (strings) into a MRPT object.
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
STL namespace.



Page generated by Doxygen 1.9.2 for MRPT 1.4.0 SVN: at Mon Sep 20 00:21:41 UTC 2021