Added documentation

This commit is contained in:
Steffen Gaisser 2020-09-07 18:35:25 +02:00
parent b65789824c
commit 0258ce62f0
2 changed files with 64 additions and 9 deletions

View File

@ -1,10 +1,10 @@
#ifndef SERIALIZEADAPTER_H_ #ifndef _FSFW_SERIALIZE_SERIALIZEADAPTER_H_
#define SERIALIZEADAPTER_H_ #define _FSFW_SERIALIZE_SERIALIZEADAPTER_H_
#include "../returnvalues/HasReturnvaluesIF.h" #include "../returnvalues/HasReturnvaluesIF.h"
#include "EndianConverter.h" #include "EndianConverter.h"
#include "SerializeIF.h" #include "SerializeIF.h"
#include <string.h> #include <cstddef>
#include <type_traits> #include <type_traits>
/** /**
@ -13,6 +13,22 @@
class SerializeAdapter { class SerializeAdapter {
public: public:
/***
* This function can be used to serialize a trivial copy-able type or a child of SerializeIF.
* The right template to be called is determined in the function itself.
* For objects of non trivial copy-able type this function is almost never called by the user directly.
* Instead helpers for specific types like SerialArrayListAdapter or SerialLinkedListAdapter is the right choice here.
*
* @param[in] object Object to serialize, the used type is deduced from this pointer
* @param[in/out] buffer Buffer to serialize into. Will be moved by the function.
* @param[in/out] size Size of current written buffer. Will be incremented by the function.
* @param[in] maxSize Max size of Buffer
* @param[in] streamEndianness Endianness of serialized element as in according to SerializeIF::Endianness
* @return
* - @c BUFFER_TOO_SHORT The given buffer in is too short
* - @c RETURN_FAILED Generic Error
* - @c RETURN_OK Successful serialization
*/
template<typename T> template<typename T>
static ReturnValue_t serialize(const T *object, uint8_t **buffer, static ReturnValue_t serialize(const T *object, uint8_t **buffer,
size_t *size, size_t maxSize, size_t *size, size_t maxSize,
@ -21,11 +37,35 @@ public:
return adapter.serialize(object, buffer, size, maxSize, return adapter.serialize(object, buffer, size, maxSize,
streamEndianness); streamEndianness);
} }
/**
* Function to return the serialized size of the object in the pointer.
* May be a trivially copy-able object or a Child of SerializeIF
*
* @param object Pointer to Object
* @return Serialized size of object
*/
template<typename T> template<typename T>
static uint32_t getSerializedSize(const T *object) { static size_t getSerializedSize(const T *object){
InternalSerializeAdapter<T, std::is_base_of<SerializeIF, T>::value> adapter; InternalSerializeAdapter<T, std::is_base_of<SerializeIF, T>::value> adapter;
return adapter.getSerializedSize(object); return adapter.getSerializedSize(object);
} }
/**
* @brief
* Deserializes a object from a given buffer of given size.
* Object Must be trivially copy-able or a child of SerializeIF.
*
* @details
* Buffer will be moved to the current read location. Size will be decreased by the function.
*
* @param[in/out] buffer Buffer to deSerialize from. Will be moved by the function.
* @param[in/out] size Remaining size of the buffer to read from. Will be decreased by function.
* @param[in] streamEndianness Endianness as in according to SerializeIF::Endianness
* @return
* - @c STREAM_TOO_SHORT The input stream is too short to deSerialize the object
* - @c TOO_MANY_ELEMENTS The buffer has more inputs than expected
* - @c RETURN_FAILED Generic Error
* - @c RETURN_OK Successful deserialization
*/
template<typename T> template<typename T>
static ReturnValue_t deSerialize(T *object, const uint8_t **buffer, static ReturnValue_t deSerialize(T *object, const uint8_t **buffer,
size_t *size, SerializeIF::Endianness streamEndianness) { size_t *size, SerializeIF::Endianness streamEndianness) {
@ -33,16 +73,26 @@ public:
return adapter.deSerialize(object, buffer, size, streamEndianness); return adapter.deSerialize(object, buffer, size, streamEndianness);
} }
private: private:
/**
* Internal template to deduce the right function calls at compile time
*/
template<typename T, bool> class InternalSerializeAdapter; template<typename T, bool> class InternalSerializeAdapter;
/**
* Template to be used if T is not a child of SerializeIF
*
* @tparam T T must be trivially_copyable
*/
template<typename T> template<typename T>
class InternalSerializeAdapter<T, false> { class InternalSerializeAdapter<T, false> {
static_assert (std::is_trivially_copyable<T>::value,
"If a type needs to be serialized it must be a child of SerializeIF or trivially copy-able");
public: public:
static ReturnValue_t serialize(const T *object, uint8_t **buffer, static ReturnValue_t serialize(const T *object, uint8_t **buffer,
size_t *size, size_t max_size, size_t *size, size_t max_size,
SerializeIF::Endianness streamEndianness) { SerializeIF::Endianness streamEndianness) {
size_t ignoredSize = 0; size_t ignoredSize = 0;
if (size == NULL) { if (size == nullptr) {
size = &ignoredSize; size = &ignoredSize;
} }
//Check remaining size is large enough and check integer overflow of *size //Check remaining size is large enough and check integer overflow of *size
@ -101,6 +151,11 @@ private:
} }
}; };
/**
* Template for objects that inherit from SerializeIF
*
* @tparam T A child of SerializeIF
*/
template<typename T> template<typename T>
class InternalSerializeAdapter<T, true> { class InternalSerializeAdapter<T, true> {
public: public:
@ -108,12 +163,12 @@ private:
size_t max_size, size_t max_size,
SerializeIF::Endianness streamEndianness) const { SerializeIF::Endianness streamEndianness) const {
size_t ignoredSize = 0; size_t ignoredSize = 0;
if (size == NULL) { if (size == nullptr) {
size = &ignoredSize; size = &ignoredSize;
} }
return object->serialize(buffer, size, max_size, streamEndianness); return object->serialize(buffer, size, max_size, streamEndianness);
} }
uint32_t getSerializedSize(const T *object) const { size_t getSerializedSize(const T *object) const {
return object->getSerializedSize(); return object->getSerializedSize();
} }
@ -124,4 +179,4 @@ private:
}; };
}; };
#endif /* SERIALIZEADAPTER_H_ */ #endif /* _FSFW_SERIALIZE_SERIALIZEADAPTER_H_ */

View File

@ -43,7 +43,7 @@ public:
* @param[in] maxSize The size of the buffer that is allowed to be used for serialize. * @param[in] maxSize The size of the buffer that is allowed to be used for serialize.
* @param[in] streamEndianness Endianness of the serialized data according to SerializeIF::Endianness * @param[in] streamEndianness Endianness of the serialized data according to SerializeIF::Endianness
* @return * @return
* - @¢ BUFFER_TOO_SHORT The given buffer in is too short * - @c BUFFER_TOO_SHORT The given buffer in is too short
* - @c RETURN_FAILED Generic error * - @c RETURN_FAILED Generic error
* - @c RETURN_OK Successful serialization * - @c RETURN_OK Successful serialization
*/ */