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:
    // construction

    CArchive();

    //
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);
    CArchive& operator << (const std::monostate&);
    CSerializable::Ptr ReadObject();

    template <typename T>
    T::Ptr ReadObject();

    virtual std::string getArchiveDescription() const;

    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:

WriteBuffer

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.

CArchive& operator << (const std::monostate&)

Requires to serialize variants without a proper value.

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

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

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.