Main MRPT website > C++ reference for MRPT 1.9.9
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-2018, 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 #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
21 {
22 namespace serialization
23 {
24 /** The virtual base class which provides a unified interface for all persistent
25  *objects in MRPT.
26  * Many important properties of this class are inherited from
27  *mrpt::rtti::CObject.
28  * Refer to the library tutorial: \ref mrpt_serialization_grp
29  * \sa CArchive
30  * \ingroup mrpt_serialization_grp
31  */
33 {
34  friend class CArchive;
35 
36  // This must be added to any CObject derived class:
38 
39  virtual ~CSerializable() {}
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  /** @} */
62 
63  public:
64  /** Introduces a pure virtual method responsible for writing to a `mxArray`
65  * Matlab object, typically a MATLAB `struct` whose contents are documented
66  * in each derived class. \return A new `mxArray` (caller is responsible of
67  * memory freeing) or nullptr is class does not support conversion to
68  * MATLAB.
69  */
70  virtual mxArray* writeToMatlab() const { return nullptr; }
71 }; // End of class def.
72 
73 /** \addtogroup noncstream_serialization Non-CStream serialization functions (in
74  * #include <mrpt/serializatin/CSerializable.h>)
75  * \ingroup mrpt_serialization_grp
76  * @{ */
77 
78 /** Converts (serializes) an MRPT object into an array of bytes.
79  * \param o The object to be serialized.
80  * \param out_vector The vector which at return will contain the data. Size will
81  * be set automatically.
82  * \sa OctetVectorToObject, ObjectToString
83  */
85  const CSerializable* o, std::vector<uint8_t>& out_vector);
86 
87 /** Converts back (de-serializes) a sequence of binary data into a MRPT object,
88  * without prior information about the object's class.
89  * \param in_data The serialized input data representing the object.
90  * \param obj The newly created object will be stored in this smart pointer.
91  * \exception None On any internal exception, this function returns a nullptr
92  * pointer.
93  * \sa ObjectToOctetVector, StringToObject
94  */
96  const std::vector<uint8_t>& in_data, CSerializable::Ptr& obj);
97 
98 /** @} */
99 
100 /** This declaration must be inserted in all CSerializable classes definition,
101  * within the class declaration. */
102 #define DEFINE_SERIALIZABLE(class_name) \
103  DEFINE_MRPT_OBJECT(class_name) \
104  protected: \
105  /*! @name CSerializable virtual methods */ \
106  /*! @{ */ \
107  uint8_t serializeGetVersion() const override; \
108  void serializeTo(mrpt::serialization::CArchive& out) const override; \
109  void serializeFrom( \
110  mrpt::serialization::CArchive& in, uint8_t serial_version) override; \
111 /*! @} */
112 
113 /** This must be inserted in all CSerializable classes implementation files */
114 #define IMPLEMENTS_SERIALIZABLE(class_name, base, NameSpace) \
115  IMPLEMENTS_MRPT_OBJECT(class_name, base, NameSpace)
116 
117 /** This declaration must be inserted in virtual CSerializable classes
118  * definition: */
119 #define DEFINE_VIRTUAL_SERIALIZABLE(class_name) \
120  DEFINE_VIRTUAL_MRPT_OBJECT(class_name)
121 
122 /** This must be inserted as implementation of some required members for
123  * virtual CSerializable classes:
124  */
125 #define IMPLEMENTS_VIRTUAL_SERIALIZABLE( \
126  class_name, base_class_name, NameSpace) \
127  IMPLEMENTS_VIRTUAL_MRPT_OBJECT(class_name, base_class_name, NameSpace)
128 
129 /** This must be inserted if a custom conversion method for MEX API is
130  * implemented in the class */
131 #define DECLARE_MEX_CONVERSION \
132  /*! @name Virtual methods for MRPT-MEX conversion */ \
133  /*! @{ */ \
134  public: \
135  mxArray* writeToMatlab() const override; \
136 /*! @} */
137 
138 /** This must be inserted if a custom conversion method for MEX API is
139  * implemented in the class */
140 #define DECLARE_MEXPLUS_FROM(complete_type) \
141  namespace mexplus \
142  { \
143  template <typename T> \
144  mxArray* from(const T& value); \
145  template <> \
146  mxArray* from(const complete_type& value); \
147  }
148 
149 #define IMPLEMENTS_MEXPLUS_FROM(complete_type) \
150  namespace mexplus \
151  { \
152  template <> \
153  mxArray* from(const complete_type& var) \
154  { \
155  return var.writeToMatlab(); \
156  } \
157  }
158 
159 } // namespace serialization
160 } // namespace mrpt
virtual void serializeTo(CArchive &out) const =0
Pure virtual method for writing (serializing) to an abstract archive.
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:37
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:252
The virtual base class of all MRPT classes with a unified RTTI system.
Definition: CObject.h:142
GLsizei GLsizei GLuint * obj
Definition: glext.h:4070
unsigned char uint8_t
Definition: rptypes.h:41
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
This is the global namespace for all Mobile Robot Programming Toolkit (MRPT) libraries.
Virtual base class for "archives": classes abstracting I/O streams.
Definition: CArchive.h:48
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:70
GLuint in
Definition: glext.h:7274
The virtual base class which provides a unified interface for all persistent objects in MRPT...
Definition: CSerializable.h:32
virtual uint8_t serializeGetVersion() const =0
Must return the current versioning number of the object.



Page generated by Doxygen 1.8.14 for MRPT 1.9.9 Git: ad3a9d8ae Tue May 1 23:10:22 2018 -0700 at lun oct 28 00:14:14 CET 2019