MRPT  2.0.4
CSerializable.h
Go to the documentation of this file.
1 /* +------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | https://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2020, Individual contributors, see AUTHORS file |
6  | See: https://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See: https://www.mrpt.org/License |
8  +------------------------------------------------------------------------+ */
9 #pragma once
10 
11 #include <mrpt/rtti/CObject.h>
13 #include <cstdint>
14 
15 // Make this frwd decl independent of MRPT_HAS_MATLAB in config.h:
16 /** Forward declaration for mxArray (avoid #including as much as possible to
17  * speed up compiling) */
18 using mxArray = struct mxArray_tag;
19 
20 namespace mrpt::serialization
21 {
22 /** The virtual base class which provides a unified interface for all persistent
23  *objects in MRPT.
24  * Many important properties of this class are inherited from
25  *mrpt::rtti::CObject.
26  * Refer to the library tutorial: \ref mrpt_serialization_grp
27  * \sa CArchive
28  * \ingroup mrpt_serialization_grp
29  */
31 {
32  friend class CArchive;
33  friend class CSchemeArchiveBase;
34 
35  // This must be added to any CObject derived class:
37 
38  ~CSerializable() override = default;
39 
40  protected:
41  /** @name CSerializable virtual methods
42  * @{ */
43  /** Must return the current versioning number of the object. Start in zero
44  * for new classes, and increments each time there is a change in the stored
45  * format.
46  */
47  virtual uint8_t serializeGetVersion() const = 0;
48  /** Pure virtual method for writing (serializing) to an abstract archive.
49  * Users don't call this method directly. Instead, use `stream << object;`.
50  * \exception std::exception On any I/O error
51  */
52  virtual void serializeTo(CArchive& out) const = 0;
53  /** Pure virtual method for reading (deserializing) from an abstract
54  *archive. Users don't call this method directly. Instead, use `stream >>
55  *object;`. \param in The input binary stream where the object data must
56  *read from. \param version The version of the object stored in the stream:
57  *use this version number in your code to know how to read the incoming
58  *data. \exception std::exception On any I/O error
59  */
60  virtual void serializeFrom(CArchive& in, uint8_t serial_version) = 0;
61  /** Virtual method for writing (serializing) to an abstract
62  * schema based archive.
63  */
64  virtual void serializeTo(CSchemeArchiveBase& out) const
65  {
66  const std::string err =
67  std::string(this->GetRuntimeClass()->className) +
68  std::string(" : class does not support schema based serialization");
69  THROW_EXCEPTION(err);
70  }
71  /** Virtual method for reading (deserializing) from an abstract
72  * schema based archive.
73  */
75  {
76  const std::string err =
77  std::string(this->GetRuntimeClass()->className) +
78  std::string(" : class does not support schema based serialization");
79  THROW_EXCEPTION(err);
80  }
81  /** @} */
82 
83  public:
84  /** Introduces a pure virtual method responsible for writing to a `mxArray`
85  * Matlab object, typically a MATLAB `struct` whose contents are documented
86  * in each derived class. \return A new `mxArray` (caller is responsible of
87  * memory freeing) or nullptr is class does not support conversion to
88  * MATLAB.
89  */
90  virtual mxArray* writeToMatlab() const { return nullptr; }
91 }; // End of class def.
92 
93 /** \addtogroup noncstream_serialization Non-CStream serialization functions (in
94  * #include <mrpt/serializatin/CSerializable.h>)
95  * \ingroup mrpt_serialization_grp
96  * @{ */
97 
98 /** Converts (serializes) an MRPT object into an array of bytes.
99  * \param o The object to be serialized.
100  * \param out_vector The vector which at return will contain the data. Size will
101  * be set automatically.
102  * \sa OctetVectorToObject, ObjectToString
103  */
105  const CSerializable* o, std::vector<uint8_t>& out_vector);
106 
107 /** Converts back (de-serializes) a sequence of binary data into a MRPT object,
108  * 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 nullptr
112  * pointer.
113  * \sa ObjectToOctetVector, StringToObject
114  */
116  const std::vector<uint8_t>& in_data, CSerializable::Ptr& obj);
117 
118 /** @} */
119 /** This declaration must be inserted in all CSerializable classes definition,
120  * within the class declaration. */
121 #define DEFINE_SCHEMA_SERIALIZABLE() \
122  protected: \
123  /*! @name CSerializable virtual methods for schema based archives*/ \
124  /*! @{ */ \
125  void serializeTo(mrpt::serialization::CSchemeArchiveBase& out) \
126  const override; \
127  void serializeFrom(mrpt::serialization::CSchemeArchiveBase& in) override; \
128 /*! @} */
129 
130 /** For use inside all serializeTo(CSchemeArchiveBase) methods */
131 #define SCHEMA_SERIALIZE_DATATYPE_VERSION(ser_version) \
132  do \
133  { \
134  out["datatype"] = std::string(this->GetRuntimeClass()->className); \
135  out["version"] = ser_version; \
136  } while (false)
137 
138 /** For use inside serializeFrom(CSchemeArchiveBase) methods */
139 #define SCHEMA_DESERIALIZE_DATATYPE_VERSION() \
140  version = static_cast<int>(in["version"]); \
141  const std::string read_typename{static_cast<std::string>(in["datatype"])}; \
142  const std::string expected_typename{this->GetRuntimeClass()->className}; \
143  if (expected_typename != read_typename) \
144  { \
145  THROW_EXCEPTION(mrpt::format( \
146  "Schema deserializing class `%s` but expected `%s`", \
147  read_typename.c_str(), expected_typename.c_str())); \
148  }
149 
150 /** This declaration must be inserted in all CSerializable classes definition,
151  * within the class declaration. */
152 #define DEFINE_SERIALIZABLE(class_name, NS) \
153  DEFINE_MRPT_OBJECT(class_name, NS) \
154  protected: \
155  /*! @name CSerializable virtual methods */ \
156  /*! @{ */ \
157  uint8_t serializeGetVersion() const override; \
158  void serializeTo(mrpt::serialization::CArchive& out) const override; \
159  void serializeFrom( \
160  mrpt::serialization::CArchive& in, uint8_t serial_version) override; \
161 /*! @} */
162 
163 /** To be added to all CSerializable-classes implementation files.
164  * This registers the class name with the NameSpace prefix.
165  */
166 #define IMPLEMENTS_SERIALIZABLE(class_name, base, NameSpace) \
167  IMPLEMENTS_MRPT_OBJECT(class_name, base, NameSpace)
168 
169 /** This declaration must be inserted in virtual CSerializable classes
170  * definition: */
171 #define DEFINE_VIRTUAL_SERIALIZABLE(class_name) \
172  DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
173 
174 /** This must be inserted as implementation of some required members for
175  * virtual CSerializable classes:
176  */
177 #define IMPLEMENTS_VIRTUAL_SERIALIZABLE(class_name, base_class, NS) \
178  IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class, NS)
179 
180 #define IMPLEMENTS_VIRTUAL_SERIALIZABLE_NS_PREFIX(class_name, base_class, NS) \
181  IMPLEMENTS_VIRTUAL_MRPT_OBJECT_NS_PREFIX(class_name, base_class, NS)
182 
183 /** This must be inserted if a custom conversion method for MEX API is
184  * implemented in the class */
185 #define DECLARE_MEX_CONVERSION \
186  /*! @name Virtual methods for MRPT-MEX conversion */ \
187  /*! @{ */ \
188  public: \
189  mxArray* writeToMatlab() const override; \
190 /*! @} */
191 
192 /** This must be inserted if a custom conversion method for MEX API is
193  * implemented in the class */
194 #define DECLARE_MEXPLUS_FROM(complete_type) \
195  namespace mexplus \
196  { \
197  template <typename T> \
198  mxArray* from(const T& value); \
199  template <> \
200  mxArray* from(const complete_type& value); \
201  }
202 
203 #define IMPLEMENTS_MEXPLUS_FROM(complete_type) \
204  namespace mexplus \
205  { \
206  template <> \
207  mxArray* from(const complete_type& var) \
208  { \
209  return var.writeToMatlab(); \
210  } \
211  }
212 } // namespace mrpt::serialization
virtual void serializeTo(CArchive &out) const =0
Pure virtual method for writing (serializing) to an abstract archive.
#define THROW_EXCEPTION(msg)
Definition: exceptions.h:67
virtual void serializeFrom(CArchive &in, uint8_t serial_version)=0
Pure virtual method for reading (deserializing) from an abstract archive.
std::shared_ptr< CSerializable > Ptr
Definition: CSerializable.h:36
virtual void serializeTo(CSchemeArchiveBase &out) const
Virtual method for writing (serializing) to an abstract schema based archive.
Definition: CSerializable.h:64
void ObjectToOctetVector(const CSerializable *o, std::vector< uint8_t > &out_vector)
Converts (serializes) an MRPT object into an array of bytes.
#define DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
This declaration must be inserted in virtual CObject classes definition:
Definition: CObject.h:293
Virtual base to provide a compiler-independent RTTI system.
Definition: CObject.h:177
Virtual base class for "schematic archives" (JSON, XML,...)
void OctetVectorToObject(const std::vector< uint8_t > &in_data, CSerializable::Ptr &obj)
Converts back (de-serializes) a sequence of binary data into a MRPT object, without prior information...
struct mxArray_tag mxArray
Forward declaration for mxArray (avoid #including as much as possible to speed up compiling) ...
Definition: CSerializable.h:18
Virtual base class for "archives": classes abstracting I/O streams.
Definition: CArchive.h:54
mrpt::vision::TStereoCalibResults out
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:90
The virtual base class which provides a unified interface for all persistent objects in MRPT...
Definition: CSerializable.h:30
virtual uint8_t serializeGetVersion() const =0
Must return the current versioning number of the object.
virtual const mrpt::rtti::TRuntimeClassId * GetRuntimeClass() const override
Returns information about the class of an object in runtime.
virtual void serializeFrom(CSchemeArchiveBase &in)
Virtual method for reading (deserializing) from an abstract schema based archive. ...
Definition: CSerializable.h:74



Page generated by Doxygen 1.8.14 for MRPT 2.0.4 Git: 33de1d0ad Sat Jun 20 11:02:42 2020 +0200 at sáb jun 20 17:35:17 CEST 2020