Data Serialization/Deserialization API

Using the Data Serialization/Deserialization API

The Data Serialization/Deserialization (SerDes) API provides serialization and deserialization of data using a simple serialization scheme. Both Data Publish/Subscribe API and RPC API support any serialization format for the transmission of the data or arguments for maximum flexibility. However, to ensure compatibility with other simulation participants, it is strongly recommended to use SerDes for all data transferred via the Data Publish/Subscribe API and the RPC API.

Caution

If other de/serialization schemes are used, it must be ensured that all other participants use this same scheme to avoid interoperability errors.

SerDes supports the following types:

• Integer values: uint8_t/sint8_t to uint64_t/sint64_t

• Boolean values: bool

• Floating-point values: float, double

• Strings: std::string

• Static and dynamic arrays aka. lists: std::vector<uint8_t>

• Dynamic byte arrays: std::vector<uint8_t>

• Structs

• Optional values

Unions are currently not supported.

Usage Example

Consider an example type from the Publish/Subscribe Demo:

struct GpsData
{
    double latitude;
    double longitude;
    std::string signalQuality;
};

Functions to serialize and deserialize this type can be written this way:

std::vector<uint8_t> Serialize(const GpsData& gpsData)
{
    SilKit::Util::SerDes::Serializer serializer;
    serializer.BeginStruct();
    serializer.Serialize(gpsData.latitude);
    serializer.Serialize(gpsData.longitude);
    serializer.Serialize(gpsData.signalQuality);
    serializer.EndStruct();

    return serializer.ReleaseBuffer();
}

GpsData Deserialize(const std::vector<uint8_t>& data)
{
    GpsData gpsData;

    SilKit::Util::SerDes::Deserializer deserializer(data);
    deserializer.BeginStruct();
    gpsData.latitude = deserializer.Deserialize<double>();
    gpsData.longitude = deserializer.Deserialize<double>();
    gpsData.signalQuality = deserializer.Deserialize<std::string>();
    deserializer.EndStruct();

    return gpsData;
}

API and Data Type Reference

The Serializer enables the serialization of data. It encapsulates a data buffer that is initially empty, with methods to consecutively serialize data into the buffer, and a method to query the serialized data as a byte vector.

The Deserializer enables the deserialization of data. It encapsulates a data buffer that is constructed from a byte vector, and provides methods to consecutively retrieve data elements from the buffer.

Serializer API

class Serializer

Public Functions

Serializer() = default

Serializer(const Serializer &other) = default

Serializer(Serializer &&other) = default

~Serializer() = default

auto operator=(const Serializer &other) -> Serializer& = default

auto operator=(Serializer &&other) -> Serializer& = default

template<typename T, typename std::enable_if<std::is_integral<T>::value && !std::is_same<bool, typename std::decay<T>::type>::value, int>::type = 0>
inline void Serialize(T data, std::size_t bitSize)

Serializes an uint8_t to uint64_t, int8_t to int64_t.

Parameters

• data – The data to be serialized.

• bitSize – The number of bits which shall be serialized.

template<typename T, typename std::enable_if_t<std::is_same<bool, typename std::decay_t<T>>::value, int> = 0>
inline void Serialize(T data)

Serializes a boolean value.

template<typename T, typename std::enable_if_t<std::is_floating_point<T>::value, int> = 0>
inline void Serialize(T data)

Serializes a float or double value. Note: long double is disabled via static assert as they are treated differently by MSVC and GCC.

Parameters

data – The primitively typed value to be serialized

inline void Serialize(std::string string)

Serializes a string.

Parameters

string – The string value to be serialized

inline void Serialize(const std::vector<uint8_t> &bytes)

Serializes a dynamic byte array.

Parameters

bytes – The bytes to be serialized

inline void BeginStruct()

Serializes the start of a struct.

inline void EndStruct()

Serializes the end of a struct.

inline void BeginArray(std::size_t size)

Serializes the start of an array or list. Note: Because the array size is serialized as well, dynamic arrays aka. lists are also supported.

Parameters

size – The number of elements

inline void EndArray()

Serializes the end of an array or list.

inline void BeginOptional(bool isAvailable)

Serializes the start of an optional value.

Parameters

isAvailable – true if the optional value is set, otherwise false. If true, the optional value must be serialized afterwards.

inline void EndOptional()

Serializes the end of an optional value.

inline void BeginUnion(const int discriminator)

Serialize the start of a union with a particular discriminator. Only the active union member must be serialized prior to calling EndUnion.

Parameters

discriminator – 1-based index of the active union member or 0 for an invalid ‘empty’ union

inline void EndUnion()

Serialize the end of a union.

inline void Reset()

Resets the buffer.

inline auto ReleaseBuffer() -> std::vector<uint8_t>

Retrieve the serialized data and release the buffer. After the call, this instance can be used to serialize a new data set.

Returns

The serialized data.

Deserializer API

class Deserializer

Public Functions

Deserializer() = default

inline Deserializer(std::vector<uint8_t> buffer)

Deserializer(const Deserializer &other) = default

Deserializer(Deserializer &&other) = default

~Deserializer() = default

auto operator=(const Deserializer &other) -> Deserializer& = default

auto operator=(Deserializer &&other) -> Deserializer& = default

template<typename T, typename std::enable_if_t<std::is_integral<T>::value && !std::is_same<bool, typename std::decay_t<T>>::value, int> = 0>
inline auto Deserialize(std::size_t bitSize) -> T

Deserializes uint8_t through uint64_t, int8_t through int64_t.

Parameters

bitSize – The number of bits which shall be deserialized.

Returns

The deserialized value

template<typename T, typename std::enable_if_t<std::is_same<bool, typename std::decay_t<T>>::value, int> = 0>
inline auto Deserialize() -> T

Deserializes a boolean value.

Returns

The deserialized value

template<typename T, typename std::enable_if_t<std::is_floating_point<T>::value, int> = 0>
inline auto Deserialize() -> T

Deserializes a float or double value.

Returns

The deserialized value

template<typename T, typename std::enable_if_t<std::is_same<std::string, T>::value, int> = 0>
inline auto Deserialize() -> T

Deserializes a string value.

Returns

The deserialized value

template<typename T, typename std::enable_if_t<std::is_same<std::vector<uint8_t>, T>::value, int> = 0>
inline auto Deserialize() -> T

Deserializes a byte array.

Returns

The deserialized value

inline void BeginStruct()

Deserializes the start of a struct.

inline void EndStruct()

Deserializes the end of a struct.

inline auto BeginArray() -> std::size_t

Deserializes the start of an array or list. Note: Because the array size is serialized as well, dynamic arrays aka. lists are also supported.

Returns

The size of the array (in elements).

inline void EndArray()

Deserializes the end of an array or list.

inline auto BeginOptional() -> bool

Deserializes the start of an optional value.

Returns

true if the value is set, otherwise false.

inline void EndOptional()

Deserializes the end of an optional value.

inline auto BeginUnion() -> int

Deserializes the start of a union and returns the discriminator. Only the active union member must be deserialized before calling EndUnion.

Returns

1-based index of the active union member or 0 for an invalid ‘empty’ union

inline void EndUnion()

Deserializes the end of a union.

inline void Reset(std::vector<uint8_t> buffer)

Resets the buffer and replaces it with another one.

Parameters

buffer – The new data buffer.

Constants

constexpr auto SilKit::Util::SerDes::v1::MediaTypeData() -> const char*

The data media / mime type the serializer / deserializer can be used for.

Returns

The data media / mime type the serializer / deserializer can be used for.

constexpr auto SilKit::Util::SerDes::v1::MediaTypeRpc() -> const char*

The RPC media / mime type the serializer / deserializer can be used for.

Returns

The RPC media / mime type the serializer / deserializer can be used for.