class mrpt::serialization::CArchive¶
Virtual base class for “archives”: classes abstracting I/O streams.
This class separates the implementation details of serialization (in CSerializable) and data storage (CArchive children: files, sockets,…).
Two main sets of implementations are provided:
archiveFrom: for MRPT mrpt::io::CArchive objects, and
CArchiveStdIStream and CArchiveStdOStream: for std::istream and std::ostream, respectively.
See also:
mrpt::io::CArchive, mrpt::serialization::CSerializable
#include <mrpt/serialization/CArchive.h> class CArchive { public: // methods size_t ReadBuffer(void* Buffer, size_t Count); template <typename T> size_t ReadBufferFixEndianness(T* ptr, size_t ElementCount); void WriteBuffer(const void* Buffer, size_t Count); template <typename T> void WriteBufferFixEndianness(const T* ptr, size_t ElementCount); template <typename STORED_TYPE, typename CAST_TO_TYPE> void ReadAsAndCastTo(CAST_TO_TYPE& read_here); template <typename STORED_TYPE> STORED_TYPE ReadAs(); void WriteObject(const CSerializable* o); CSerializable::Ptr ReadObject(); template <typename T> T::Ptr ReadObject(); template <typename... T> std::variant<T...> ReadVariant(); template <typename T> void WriteVariant(T t); template <typename T> T ReadPOD(); void ReadObject(CSerializable* existingObj); void sendMessage(const CMessage& msg); bool receiveMessage(CMessage& msg); CArchive& operator << (const CSerializable& obj); CArchive& operator << (const CSerializable::Ptr& pObj); CArchive& operator >> (CSerializable& obj); CArchive& operator >> (CSerializable::Ptr& pObj); }; // direct descendants template <class STREAM> class CArchiveStreamBase; template <> class CArchiveStreamBase<const std::vector<uint8_t>>; template <> class CArchiveStreamBase<std::iostream>; template <> class CArchiveStreamBase<std::istream>; template <> class CArchiveStreamBase<std::ostream>; template <> class CArchiveStreamBase<std::vector<uint8_t>>;
Methods¶
size_t ReadBuffer(void* Buffer, size_t Count)
Reads a block of bytes from the stream into Buffer.
This method is endianness-dependent.
Parameters:
std::exception |
On any error, or if ZERO bytes are read. |
Returns:
The amound of bytes actually read.
See also:
ReadBufferImmediate ; Important, see: ReadBufferFixEndianness,
template <typename T> size_t ReadBufferFixEndianness( T* ptr, size_t ElementCount )
Reads a sequence of elemental datatypes, taking care of reordering their bytes from the MRPT stream standard (little endianness) to the format of the running architecture.
Parameters:
ElementCount |
The number of elements (not bytes) to read. |
ptr |
A pointer to the first output element in an array (or std::vector<>, etc…). |
std::exception |
On any error, or if ZERO bytes are read. |
Returns:
The amound of bytes (not elements) actually read (under error situations, the last element may be invalid if the data stream abruptly ends). Example of usage:
uint32_t N; s >> N; vector<float> vec(N); if (N) s.ReadBufferFixEndianness<float>(&vec[0],N);
See also:
ReadBufferFixEndianness, ReadBuffer
void WriteBuffer(const void* Buffer, size_t Count)
Writes a block of bytes to the stream from Buffer.
This method is endianness-dependent.
Parameters:
std::exception |
On any error |
See also:
Important, see: WriteBufferFixEndianness
template <typename T> void WriteBufferFixEndianness( const T* ptr, size_t ElementCount )
Writes a sequence of elemental datatypes, taking care of reordering their bytes from the running architecture to MRPT stream standard (little endianness).
Parameters:
ElementCount |
The number of elements (not bytes) to write. |
ptr |
A pointer to the first input element in an array (or std::vector<>, etc…). Example of usage: vector<float> vec = ... uint32_t N = vec.size(); s << N if (N) s.WriteBufferFixEndianness<float>(&vec[0],N); |
std::exception |
On any error |
See also:
template <typename STORED_TYPE, typename CAST_TO_TYPE> void ReadAsAndCastTo(CAST_TO_TYPE& read_here)
Read a value from a stream stored in a type different of the target variable, making the conversion via static_cast.
Useful for coding backwards compatible de-serialization blocks
template <typename STORED_TYPE> STORED_TYPE ReadAs()
De-serialize a variable and returns it by value.
void WriteObject(const CSerializable* o)
Writes an object to the stream.
CSerializable::Ptr ReadObject()
Reads an object from stream, its class determined at runtime, and returns a smart pointer to the object.
Parameters:
std::exception |
On I/O error or undefined class. |
On an End-Of-File condition found at a correct place: an EOF that abruptly finishes in the middle of one object raises a plain std::exception instead. |
template <typename T> T::Ptr ReadObject()
Reads an object from stream, its class determined at runtime, and returns a smart pointer to the object.
This version is similar to std::make_shared<T>.
Parameters:
std::exception |
On I/O error or undefined class. |
On an End-Of-File condition found at a correct place: an EOF that abruptly finishes in the middle of one object raises a plain std::exception instead. |
template <typename... T> std::variant<T...> ReadVariant()
Reads a variant from stream, its class determined at runtime, and returns a variant to the object.
To be compatible with the current polymorphic system this support smart pointer types. For pointer types, This will bind to the first possible pointer type. variant<CSerializable::Ptr, CRenderizable::Ptr>
Parameters:
std::exception |
On I/O error or undefined class. |
On an End-Of-File condition found at a correct place: an EOF that abruptly finishes in the middle of one object raises a plain std::exception instead. |
template <typename T> void WriteVariant(T t)
Writes a Variant to the stream.
template <typename T> T ReadPOD()
Reads a simple POD type and returns by value.
Useful when stream >> var; cannot be used becuase of errors of misaligned reference binding. Use with macro MRPT_READ_POD to avoid typing the type T yourself. [New in MRPT 2.0.0]
Write operator s << var; is safe for misaligned variables.
void ReadObject(CSerializable* existingObj)
Reads an object from stream, where its class must be the same as the supplied object, where the loaded object will be stored in.
Parameters:
std::exception |
On I/O error or different class found. |
On an End-Of-File condition found at a correct place: an EOF that abruptly finishes in the middle of one object raises a plain std::exception instead. |
void sendMessage(const CMessage& msg)
Send a message to the device.
Note that only the low byte from the “type” field will be used.
For frames of size < 255 the frame format is an array of bytes in this order:
<START_FLAG> <HEADER> <LENGTH> <BODY> <END_FLAG> <START_FLAG> = 0x69 <HEADER> = A header byte <LENGHT> = Number of bytes of BODY <BODY> = N x bytes <END_FLAG> = 0X96 Total length = <LENGTH> + 4
For frames of size > 255 the frame format is an array of bytes in this order:
<START_FLAG> <HEADER> <HIBYTE(LENGTH)> <LOBYTE(LENGTH)> <BODY> <END_FLAG> <START_FLAG> = 0x79 <HEADER> = A header byte <LENGHT> = Number of bytes of BODY <BODY> = N x bytes <END_FLAG> = 0X96 Total length = <LENGTH> + 5
Parameters:
std::exception |
On communication errors |
bool receiveMessage(CMessage& msg)
Tries to receive a message from the device.
Parameters:
std::exception |
On communication errors |
Returns:
True if successful, false if there is no new data from the device (but communications seem to work fine)
See also:
The frame format is described in sendMessage()
CArchive& operator << (const CSerializable& obj)
Write a CSerializable object to a stream in the binary MRPT format.
Write an object to a stream in the binary MRPT format.
CArchive& operator << (const CSerializable::Ptr& pObj)
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
CArchive& operator >> (CSerializable& obj)
Reads a CSerializable object from the stream.
CArchive& operator >> (CSerializable::Ptr& pObj)
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.