Serializable.hpp

Go to the documentation of this file.

#ifndef SERIALIZABLE_HPP
#define SERIALIZABLE_HPP

#ifdef BUILD_UT
#include <iostream>
#endif

#include <Fw/FPrimeBasicTypes.hpp>
#include "Fw/Deprecate.hpp"

namespace Fw {

class StringBase;  
typedef enum {
    FW_SERIALIZE_OK,                  
    FW_SERIALIZE_FORMAT_ERROR,        
    FW_SERIALIZE_NO_ROOM_LEFT,        
    FW_DESERIALIZE_BUFFER_EMPTY,      
    FW_DESERIALIZE_FORMAT_ERROR,      
    FW_DESERIALIZE_SIZE_MISMATCH,     
    FW_DESERIALIZE_TYPE_MISMATCH,     
    FW_DESERIALIZE_IMMUTABLE,         
    FW_SERIALIZE_DISCARDED_EXISTING,  
} SerializeStatus;

class SerialBufferBase;  
class LinearBufferBase;  

// TODO: Temporary backwards-compatibility hack. Remove this when all references to SerializeBufferBase are migrated.
using SerializeBufferBase = LinearBufferBase;

struct Serialization {
    enum t {
        INCLUDE_LENGTH,  
        OMIT_LENGTH      
    };
};

enum class Endianness {
    BIG,    
    LITTLE  
};

class Serializable {
  public:
    // Size type for backwards compatibility
    using SizeType = FwSizeType;

  public:
    virtual SerializeStatus serializeTo(SerialBufferBase& buffer, Endianness mode = Endianness::BIG) const = 0;

    virtual SerializeStatus deserializeFrom(SerialBufferBase& buffer, Endianness mode = Endianness::BIG) = 0;

    // ----------------------------------------------------------------------
    // Legacy methods for backward compatibility
    // ----------------------------------------------------------------------

    DEPRECATED(SerializeStatus serialize(SerialBufferBase& buffer) const,
               "Use serializeTo(SerialBufferBase& buffer) instead") {
        return this->serializeTo(buffer);
    }

    DEPRECATED(SerializeStatus deserialize(SerialBufferBase& buffer),
               "Use deserializeFrom(SerialBufferBase& buffer) instead") {
        return this->deserializeFrom(buffer);
    }

#if FW_SERIALIZABLE_TO_STRING || FW_ENABLE_TEXT_LOGGING || BUILD_UT
    virtual void toString(StringBase& text) const;
#endif

#ifdef BUILD_UT
    friend std::ostream& operator<<(std::ostream& os, const Serializable& val);
#endif

  protected:
    Serializable();

    virtual ~Serializable();
};

class SerialBufferBase {
  public:
    virtual ~SerialBufferBase();

    // Serialization for built-in types

    virtual SerializeStatus serializeFrom(U8 val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(I8 val, Endianness mode = Endianness::BIG) = 0;

#if FW_HAS_16_BIT == 1
    virtual SerializeStatus serializeFrom(U16 val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(I16 val, Endianness mode = Endianness::BIG) = 0;
#endif
#if FW_HAS_32_BIT == 1
    virtual SerializeStatus serializeFrom(U32 val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(I32 val, Endianness mode = Endianness::BIG) = 0;
#endif
#if FW_HAS_64_BIT == 1
    virtual SerializeStatus serializeFrom(U64 val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(I64 val, Endianness mode = Endianness::BIG) = 0;
#endif
    virtual SerializeStatus serializeFrom(F32 val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(F64 val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(bool val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(const void* val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(const U8* buff,
                                          FwSizeType length,
                                          Endianness endianMode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(const U8* buff,
                                          FwSizeType length,
                                          Serialization::t lengthMode,
                                          Endianness endianMode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(const LinearBufferBase& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeFrom(const Serializable& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus serializeSize(const FwSizeType size, Endianness mode = Endianness::BIG) = 0;

    // Deserialization for built-in types

    virtual SerializeStatus deserializeTo(U8& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(I8& val, Endianness mode = Endianness::BIG) = 0;

#if FW_HAS_16_BIT == 1
    virtual SerializeStatus deserializeTo(U16& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(I16& val, Endianness mode = Endianness::BIG) = 0;
#endif

#if FW_HAS_32_BIT == 1
    virtual SerializeStatus deserializeTo(U32& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(I32& val, Endianness mode = Endianness::BIG) = 0;
#endif
#if FW_HAS_64_BIT == 1
    virtual SerializeStatus deserializeTo(U64& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(I64& val, Endianness mode = Endianness::BIG) = 0;
#endif
    virtual SerializeStatus deserializeTo(F32& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(F64& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(bool& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(void*& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(U8* buff, FwSizeType& length, Endianness endianMode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(U8* buff,
                                          FwSizeType& length,
                                          Serialization::t lengthMode,
                                          Endianness endianMode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(Serializable& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeTo(LinearBufferBase& val, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus deserializeSize(FwSizeType& size, Endianness mode = Endianness::BIG) = 0;

    virtual SerializeStatus copyRaw(SerialBufferBase& dest, Serializable::SizeType size) = 0;

    virtual SerializeStatus copyRawOffset(SerialBufferBase& dest, Serializable::SizeType size) = 0;

    virtual void resetSer() = 0;

    virtual void resetDeser() = 0;

    virtual SerializeStatus moveSerToOffset(FwSizeType offset) = 0;

    virtual SerializeStatus moveDeserToOffset(FwSizeType offset) = 0;

    virtual SerializeStatus serializeSkip(FwSizeType numBytesToSkip) = 0;

    virtual SerializeStatus deserializeSkip(FwSizeType numBytesToSkip) = 0;

    virtual Serializable::SizeType getCapacity() const = 0;

    virtual Serializable::SizeType getSize() const = 0;

    virtual Serializable::SizeType getDeserializeSizeLeft() const = 0;

    virtual Serializable::SizeType getSerializeSizeLeft() const = 0;

    virtual SerializeStatus setBuff(const U8* src, Serializable::SizeType length) = 0;

    virtual SerializeStatus setBuffLen(Serializable::SizeType length) = 0;
};

class LinearBufferBase : public SerialBufferBase {
    friend class SerializeBufferBaseTester;

  protected:
    LinearBufferBase& operator=(const LinearBufferBase& src);

  public:
    virtual ~LinearBufferBase();

    // Serialization for built-in types

    SerializeStatus serializeFrom(U8 val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(I8 val, Endianness mode = Endianness::BIG) override;

#if FW_HAS_16_BIT == 1
    SerializeStatus serializeFrom(U16 val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(I16 val, Endianness mode = Endianness::BIG) override;
#endif
#if FW_HAS_32_BIT == 1
    SerializeStatus serializeFrom(U32 val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(I32 val, Endianness mode = Endianness::BIG) override;
#endif
#if FW_HAS_64_BIT == 1
    SerializeStatus serializeFrom(U64 val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(I64 val, Endianness mode = Endianness::BIG) override;
#endif
    SerializeStatus serializeFrom(F32 val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(F64 val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(bool val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(const void* val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(const U8* buff, FwSizeType length, Endianness endianMode = Endianness::BIG) override;

    SerializeStatus serializeFrom(const U8* buff,
                                  FwSizeType length,
                                  Serialization::t lengthMode,
                                  Endianness endianMode = Endianness::BIG) override;

    SerializeStatus serializeFrom(const LinearBufferBase& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeFrom(const Serializable& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus serializeSize(const FwSizeType size, Endianness mode = Endianness::BIG) override;

    // Deserialization for built-in types

    SerializeStatus deserializeTo(U8& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(I8& val, Endianness mode = Endianness::BIG) override;

#if FW_HAS_16_BIT == 1
    SerializeStatus deserializeTo(U16& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(I16& val, Endianness mode = Endianness::BIG) override;
#endif

#if FW_HAS_32_BIT == 1
    SerializeStatus deserializeTo(U32& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(I32& val, Endianness mode = Endianness::BIG) override;
#endif
#if FW_HAS_64_BIT == 1
    SerializeStatus deserializeTo(U64& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(I64& val, Endianness mode = Endianness::BIG) override;
#endif
    SerializeStatus deserializeTo(F32& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(F64& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(bool& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(void*& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(U8* buff, FwSizeType& length, Endianness endianMode = Endianness::BIG) override;

    SerializeStatus deserializeTo(U8* buff,
                                  FwSizeType& length,
                                  Serialization::t lengthMode,
                                  Endianness endianMode = Endianness::BIG) override;

    SerializeStatus deserializeTo(Serializable& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeTo(LinearBufferBase& val, Endianness mode = Endianness::BIG) override;

    SerializeStatus deserializeSize(FwSizeType& size, Endianness mode = Endianness::BIG) override;

    DEPRECATED(SerializeStatus serialize(const LinearBufferBase& val),
               "Use serializeFrom(const SerialBufferBase& val) instead");
    DEPRECATED(SerializeStatus deserialize(LinearBufferBase& val), "Use deserializeTo(SerialBufferBase& val) instead");

    void resetSer() override;

    void resetDeser() override;

    SerializeStatus moveSerToOffset(FwSizeType offset) override;

    SerializeStatus moveDeserToOffset(FwSizeType offset) override;

    SerializeStatus serializeSkip(FwSizeType numBytesToSkip) override;

    SerializeStatus deserializeSkip(FwSizeType numBytesToSkip) override;

    DEPRECATED(Serializable::SizeType getBuffCapacity() const, "Use getCapacity() instead");
    DEPRECATED(Serializable::SizeType getBuffLength() const, "Use getSize() instead");
    DEPRECATED(Serializable::SizeType getBuffLeft(), "Use getDeserializeSizeLeft() instead");

    Serializable::SizeType getCapacity() const override = 0;

    Serializable::SizeType getSize() const override;

    Serializable::SizeType getDeserializeSizeLeft() const override;

    Serializable::SizeType getSerializeSizeLeft() const override;

    virtual U8* getBuffAddr() = 0;

    virtual const U8* getBuffAddr() const = 0;

    const U8* getBuffAddrLeft() const;

    U8* getBuffAddrSer();

    SerializeStatus setBuff(const U8* src, Serializable::SizeType length) override;

    SerializeStatus setBuffLen(Serializable::SizeType length) override;

    SerializeStatus copyRaw(SerialBufferBase& dest, Serializable::SizeType size) override;

    SerializeStatus copyRawOffset(SerialBufferBase& dest, Serializable::SizeType size) override;

    // ----------------------------------------------------------------------
    // Deprecated Serialization methods
    // ----------------------------------------------------------------------

    DEPRECATED(SerializeStatus serialize(U8 val), "Use serializeFrom(U8 val) instead");
    DEPRECATED(SerializeStatus serialize(I8 val), "Use serializeFrom(I8 val) instead");
#if FW_HAS_16_BIT == 1
    DEPRECATED(SerializeStatus serialize(U16 val), "Use serializeFrom(U16 val) instead");
    DEPRECATED(SerializeStatus serialize(I16 val), "Use serializeFrom(I16 val) instead");
#endif
#if FW_HAS_32_BIT == 1
    DEPRECATED(SerializeStatus serialize(U32 val), "Use serializeFrom(U32 val) instead");
    DEPRECATED(SerializeStatus serialize(I32 val), "Use serializeFrom(I32 val) instead");
#endif
#if FW_HAS_64_BIT == 1
    DEPRECATED(SerializeStatus serialize(U64 val), "Use serializeFrom(U64 val) instead");
    DEPRECATED(SerializeStatus serialize(I64 val), "Use serializeFrom(I64 val) instead");
#endif

    DEPRECATED(SerializeStatus serialize(F32 val), "Use serializeFrom(F32 val) instead");
    DEPRECATED(SerializeStatus serialize(F64 val), "Use serializeFrom(F64 val) instead");
    DEPRECATED(SerializeStatus serialize(bool val), "Use serializeFrom(bool val) instead");
    DEPRECATED(SerializeStatus serialize(const void* val), "Use serializeFrom(const void* val) instead");
    DEPRECATED(SerializeStatus serialize(const U8* buff, FwSizeType length, bool noLength),
               "Use serialize(const U8* buff, FwSizeType length, Serialization::t mode) instead");
    DEPRECATED(SerializeStatus serialize(const U8* buff, FwSizeType length),
               "Use serializeFrom(const U8* buff, FwSizeType length) instead");
    DEPRECATED(SerializeStatus serialize(const U8* buff, FwSizeType length, Serialization::t mode),
               "Use serializeFrom(const U8* buff, FwSizeType length, Serialization::t mode) instead");
    DEPRECATED(SerializeStatus serialize(const Serializable& val),
               "Use serializeFrom(const Serializable& val) instead");

    DEPRECATED(SerializeStatus deserialize(U8& val), "Use deserializeTo(U8& val) instead");
    DEPRECATED(SerializeStatus deserialize(I8& val), "Use deserializeTo(I8& val) instead");
#if FW_HAS_16_BIT == 1
    DEPRECATED(SerializeStatus deserialize(U16& val), "Use deserializeTo(U16& val) instead");
    DEPRECATED(SerializeStatus deserialize(I16& val), "Use deserializeTo(I16& val) instead");
#endif
#if FW_HAS_32_BIT == 1
    DEPRECATED(SerializeStatus deserialize(U32& val), "Use deserializeTo(U32& val) instead");
    DEPRECATED(SerializeStatus deserialize(I32& val), "Use deserializeTo(I32& val) instead");
#endif
#if FW_HAS_64_BIT == 1
    DEPRECATED(SerializeStatus deserialize(U64& val), "Use deserializeTo(U64& val) instead");
    DEPRECATED(SerializeStatus deserialize(I64& val), "Use deserializeTo(I64& val) instead");
#endif

    DEPRECATED(SerializeStatus deserialize(F32& val), "Use deserializeTo(F32& val) instead");
    DEPRECATED(SerializeStatus deserialize(F64& val), "Use deserializeTo(F64& val) instead");
    DEPRECATED(SerializeStatus deserialize(bool& val), "Use deserializeTo(bool& val) instead");
    DEPRECATED(SerializeStatus deserialize(void*& val), "Use deserializeTo(void*& val) instead");
    DEPRECATED(SerializeStatus deserialize(U8* buff, FwSizeType& length, bool noLength),
               "Use deserialize(U8* buff, FwSizeType& length, Serialization::t mode) instead");
    DEPRECATED(SerializeStatus deserialize(U8* buff, FwSizeType& length),
               "Use deserializeTo(U8* buff, FwSizeType& length) instead");
    DEPRECATED(SerializeStatus deserialize(U8* buff, FwSizeType& length, Serialization::t mode),
               "Use deserializeTo(U8* buff, FwSizeType& length, Serialization::t mode) instead");
    DEPRECATED(SerializeStatus deserialize(Serializable& val), "Use deserializeTo(Serializable& val) instead");

#ifdef BUILD_UT
    bool operator==(const LinearBufferBase& other) const;

    friend std::ostream& operator<<(std::ostream& os, const LinearBufferBase& buff);
#endif

  protected:
    LinearBufferBase();

    LinearBufferBase(const LinearBufferBase& src);

    void copyFrom(const LinearBufferBase& src);

    Serializable::SizeType m_serLoc;    
    Serializable::SizeType m_deserLoc;  

  private:
};

// Helper classes for building buffers with external storage

class ExternalSerializeBuffer : public LinearBufferBase {
  public:
    ExternalSerializeBuffer(U8* buffPtr, Serializable::SizeType size);

    ExternalSerializeBuffer();

    ~ExternalSerializeBuffer() {}

    void setExtBuffer(U8* buffPtr, Serializable::SizeType size);

    void clear();

    ExternalSerializeBuffer(const ExternalSerializeBuffer& src) = delete;

    DEPRECATED(Serializable::SizeType getBuffCapacity() const, "Use getCapacity() instead");

    Serializable::SizeType getCapacity() const;

    U8* getBuffAddr();

    const U8* getBuffAddr() const;

    ExternalSerializeBuffer& operator=(const LinearBufferBase& src) = delete;

  protected:
    // data members
    U8* m_buff;                         
    Serializable::SizeType m_buffSize;  
};

class ExternalSerializeBufferWithDataCopy final : public ExternalSerializeBuffer {
  public:
    ExternalSerializeBufferWithDataCopy(U8* buffPtr, Serializable::SizeType size)
        : ExternalSerializeBuffer(buffPtr, size) {}

    ExternalSerializeBufferWithDataCopy() : ExternalSerializeBuffer() {}

    ~ExternalSerializeBufferWithDataCopy() {}

    ExternalSerializeBufferWithDataCopy(const LinearBufferBase& src) = delete;

    ExternalSerializeBufferWithDataCopy& operator=(LinearBufferBase& src) {
        (void)LinearBufferBase::operator=(src);
        return *this;
    }
};

class ExternalSerializeBufferWithMemberCopy final : public ExternalSerializeBuffer {
  public:
    ExternalSerializeBufferWithMemberCopy(U8* buffPtr, Serializable::SizeType size)
        : ExternalSerializeBuffer(buffPtr, size) {}

    ExternalSerializeBufferWithMemberCopy() : ExternalSerializeBuffer() {}

    ~ExternalSerializeBufferWithMemberCopy() {}

    ExternalSerializeBufferWithMemberCopy(const ExternalSerializeBufferWithMemberCopy& src)
        : ExternalSerializeBuffer(src.m_buff, src.m_buffSize) {
        this->m_serLoc = src.m_serLoc;
        this->m_deserLoc = src.m_deserLoc;
    }

    ExternalSerializeBufferWithMemberCopy& operator=(const ExternalSerializeBufferWithMemberCopy& src) {
        // Ward against self-assignment
        if (this != &src) {
            this->clear();
            this->m_buff = src.m_buff;
            this->m_buffSize = src.m_buffSize;
            this->m_serLoc = src.m_serLoc;
            this->m_deserLoc = src.m_deserLoc;
        }
        return *this;
    }
};

}  // namespace Fw
#endif