Class CArchive

Inheritance Relationships

Derived Types

Class Documentation

class 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

Subclassed by mrpt::serialization::CArchiveStreamBase< STREAM >, mrpt::serialization::CArchiveStreamBase< const std::vector< uint8_t > >, mrpt::serialization::CArchiveStreamBase< std::iostream >, mrpt::serialization::CArchiveStreamBase< std::istream >, mrpt::serialization::CArchiveStreamBase< std::ostream >, mrpt::serialization::CArchiveStreamBase< std::vector< uint8_t > >

Serialization API for generic “archives” I/O streams

size_t ReadBuffer(void *Buffer, size_t Count)

Reads a block of bytes from the stream into Buffer

See also

ReadBufferImmediate ; Important, see: ReadBufferFixEndianness,

Note

This method is endianness-dependent.

Throws:

std::exception – On any error, or if ZERO bytes are read.

Returns:

The amound of bytes actually read.

template<typename T>
inline 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.

See also

ReadBufferFixEndianness, ReadBuffer

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…).

Throws:

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);

void WriteBuffer(const void *Buffer, size_t Count)

Writes a block of bytes to the stream from Buffer.

See also

Important, see: WriteBufferFixEndianness

Note

This method is endianness-dependent.

Throws:

std::exception – On any error

template<typename T>
inline 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).

See also

WriteBuffer

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);

Throws:

std::exception – On any error

template<typename STORED_TYPE, typename CAST_TO_TYPE>
inline 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>
inline STORED_TYPE ReadAs()

De-serialize a variable and returns it by value.

template<typename TYPE_TO_STORE, typename TYPE_FROM_ACTUAL>
inline CArchive &WriteAs(const TYPE_FROM_ACTUAL &value)
void WriteObject(const CSerializable *o)

Writes an object to the stream.

inline void WriteObject(const CSerializable &o)
CArchive &operator<<(const std::monostate&)

Requires to serialize variants without a proper value.

inline CSerializable::Ptr ReadObject()

Reads an object from stream, its class determined at runtime, and returns a smart pointer to the object.

Throws:

  • std::exception – On I/O error or undefined class.

  • CExceptionEOF – 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>
inline 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>.

Throws:

  • std::exception – On I/O error or undefined class.

  • CExceptionEOF – 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.

inline virtual std::string getArchiveDescription() const

If redefined in derived classes, allows finding a human-friendly description of the underlying stream (e.g. filename)

template<typename ...T>
inline 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>

Throws:

  • std::exception – On I/O error or undefined class.

  • CExceptionEOF – 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>
inline void WriteVariant(T t)

Writes a Variant to the stream

template<typename T>
inline T ReadPOD()

Reads a simple POD type and returns by value. Useful when stream >> var; cannot be used because of errors of misaligned reference binding. Use with macro MRPT_READ_POD to avoid typing the type T yourself.

Note

[New in MRPT 2.0.0]

Note

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.

Throws:

  • std::exception – On I/O error or different class found.

  • CExceptionEOF – 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

Throws:

std::exception – On communication errors

bool receiveMessage(CMessage &msg)

Tries to receive a message from the device.

See also

The frame format is described in sendMessage()

Throws:

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)

CArchive &operator<<(const CSerializable &obj)

Write a CSerializable 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.

Virtual methods of the CArchive interface

virtual size_t write(const void *buf, size_t len) = 0

Writes a block of bytes.

Throws:

std::exception – On any error

Returns:

Number of bytes actually written.

virtual size_t read(void *buf, size_t len) = 0

Reads a block of bytes.

Throws:

std::exception – On any error, or if ZERO bytes are read.

Returns:

Number of bytes actually read if >0.

Public Types

using Ptr = std::shared_ptr<CArchive>
using UniquePtr = std::unique_ptr<CArchive>

Public Functions

CArchive() = default
virtual ~CArchive() = default

Protected Functions

void internal_ReadObject(CSerializable *newObj, const std::string &className, bool isOldFormat, uint8_t version)

Read the object

void internal_ReadObjectHeader(std::string &className, bool &isOldFormat, uint8_t &version)

Read the object Header