Merge pull request 'Some minor serialize file changes' (#185) from KSat/fsfw:mueller/serialize-convergence into master

Reviewed-on: fsfw/fsfw#185

serialize/EndianConverter.h

@@ -1,5 +1,5 @@
-#ifndef ENDIANSWAPPER_H_
+#ifndef FSFW_SERIALIZE_ENDIANCONVERTER_H_
-#define ENDIANSWAPPER_H_
+#define FSFW_SERIALIZE_ENDIANCONVERTER_H_
 
 #include "../osal/Endiness.h"
 #include <cstring>
@@ -35,9 +35,7 @@
  */
 class EndianConverter {
 private:
-	EndianConverter() {
+	EndianConverter() {};
-	}
-	;
 public:
 	/**
 	 * Convert a typed variable between big endian and machine endian.
@@ -123,4 +121,4 @@ public:
 	}
 };
 
-#endif /* ENDIANSWAPPER_H_ */
+#endif /* FSFW_SERIALIZE_ENDIANCONVERTER_H_ */

serialize/SerialArrayListAdapter.h

@@ -1,13 +1,14 @@
-#ifndef FRAMEWORK_SERIALIZE_SERIALARRAYLISTADAPTER_H_
+#ifndef FSFW_SERIALIZE_SERIALARRAYLISTADAPTER_H_
-#define FRAMEWORK_SERIALIZE_SERIALARRAYLISTADAPTER_H_
+#define FSFW_SERIALIZE_SERIALARRAYLISTADAPTER_H_
 
-#include "../container/ArrayList.h"
 #include "SerializeIF.h"
+#include "../container/ArrayList.h"
 #include <utility>
 
 /**
+ * Also serializes length field !
+ * @author 	baetz
  * @ingroup serialize
- * @author  baetz
  */
 template<typename T, typename count_t = uint8_t>
 class SerialArrayListAdapter : public SerializeIF {
@@ -21,14 +22,14 @@ public:
 	}
 
 	static ReturnValue_t serialize(const ArrayList<T, count_t>* list,
-	        uint8_t** buffer, size_t* size, size_t maxSize,
+			uint8_t** buffer, size_t* size, size_t maxSize,
-	        Endianness streamEndianness) {
+			Endianness streamEndianness) {
 		ReturnValue_t result = SerializeAdapter::serialize(&list->size,
 				buffer, size, maxSize, streamEndianness);
 		count_t i = 0;
 		while ((result == HasReturnvaluesIF::RETURN_OK) && (i < list->size)) {
-			result = SerializeAdapter::serialize(&list->entries[i], buffer,
+			result = SerializeAdapter::serialize(&list->entries[i], buffer, size,
-			        size, maxSize, streamEndianness);
+					maxSize, streamEndianness);
 			++i;
 		}
 		return result;
@@ -55,17 +56,18 @@ public:
 	}
 
 	static ReturnValue_t deSerialize(ArrayList<T, count_t>* list,
-	        const uint8_t** buffer, size_t* size,
+			const uint8_t** buffer, size_t* size,
 			Endianness streamEndianness) {
 		count_t tempSize = 0;
 		ReturnValue_t result = SerializeAdapter::deSerialize(&tempSize,
 				buffer, size, streamEndianness);
 		if(result != HasReturnvaluesIF::RETURN_OK) {
-		    return result;
+			return result;
 		}
 		if (tempSize > list->maxSize()) {
 			return SerializeIF::TOO_MANY_ELEMENTS;
 		}
+
 		list->size = tempSize;
 		count_t i = 0;
 		while ((result == HasReturnvaluesIF::RETURN_OK) && (i < list->size)) {
@@ -76,10 +78,9 @@ public:
 		}
 		return result;
 	}
+
 private:
 	ArrayList<T, count_t> *adaptee;
 };
 
-
+#endif /* FSFW_SERIALIZE_SERIALARRAYLISTADAPTER_H_ */
-
-#endif /* FRAMEWORK_SERIALIZE_SERIALARRAYLISTADAPTER_H_ */

serialize/SerialFixedArrayListAdapter.h

@@ -1,31 +1,57 @@
-#ifndef SERIALFIXEDARRAYLISTADAPTER_H_
+#ifndef FSFW_SERIALIZE_SERIALFIXEDARRAYLISTADAPTER_H_
-#define SERIALFIXEDARRAYLISTADAPTER_H_
+#define FSFW_SERIALIZE_SERIALFIXEDARRAYLISTADAPTER_H_
 
-#include "../container/FixedArrayList.h"
 #include "SerialArrayListAdapter.h"
+#include "../container/FixedArrayList.h"
 
 /**
- * \ingroup serialize
+ * @brief 	This adapter provides an interface for SerializeIF to serialize and
+ * 			deserialize buffers with a header containing the buffer length.
+ * @details
+ * Can be used by SerialLinkedListAdapter by declaring
+ * as a linked element with SerializeElement<SerialFixedArrayListAdapter<...>>.
+ * The sequence of objects is defined in the constructor by
+ * using the setStart and setNext functions.
+ *
+ * @tparam BUFFER_TYPE: Specifies the data type of the buffer
+ * @tparam MAX_SIZE: Specifies the maximum allowed number of elements
+ * 					 (not bytes!)
+ * @tparam count_t: specifies the type/size of the length field which defaults
+ * 					to one byte.
+ * @ingroup serialize
  */
-template<typename T, uint32_t MAX_SIZE, typename count_t = uint8_t>
+template<typename BUFFER_TYPE, uint32_t MAX_SIZE, typename count_t = uint8_t>
-class SerialFixedArrayListAdapter : public FixedArrayList<T, MAX_SIZE, count_t>, public SerializeIF {
+class SerialFixedArrayListAdapter :
+		public FixedArrayList<BUFFER_TYPE, MAX_SIZE, count_t>,
+		public SerializeIF {
 public:
+	/**
+	 * Constructor arguments are forwarded to FixedArrayList constructor.
+	 * Refer to the fixed array list constructors for different options.
+	 * @param args
+	 */
 	template<typename... Args>
-	SerialFixedArrayListAdapter(Args... args) : FixedArrayList<T, MAX_SIZE, count_t>(std::forward<Args>(args)...) {
+	SerialFixedArrayListAdapter(Args... args) :
-	}
+	        FixedArrayList<BUFFER_TYPE, MAX_SIZE, count_t>(
-	ReturnValue_t serialize(uint8_t** buffer, size_t* size,
+	        std::forward<Args>(args)...){}
-			size_t maxSize, Endianness streamEndianness) const {
+
-		return SerialArrayListAdapter<T, count_t>::serialize(this, buffer, size, maxSize, streamEndianness);
+    ReturnValue_t serialize(uint8_t** buffer, size_t* size,
-	}
+            size_t maxSize, Endianness streamEndianness) const {
-	size_t getSerializedSize() const {
+        return SerialArrayListAdapter<BUFFER_TYPE, count_t>::serialize(this,
-		return SerialArrayListAdapter<T, count_t>::getSerializedSize(this);
+                buffer, size, maxSize, streamEndianness);
-	}
+    }
-	ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size,
+
-			Endianness streamEndianness) {
+    size_t getSerializedSize() const {
-		return SerialArrayListAdapter<T, count_t>::deSerialize(this, buffer, size, streamEndianness);
+        return SerialArrayListAdapter<BUFFER_TYPE, count_t>::
-	}
+        		getSerializedSize(this);
+    }
+
+    ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size,
+            Endianness streamEndianness) {
+        return SerialArrayListAdapter<BUFFER_TYPE, count_t>::deSerialize(this,
+                buffer, size, streamEndianness);
+    }
+
 };
 
-
+#endif /* FSFW_SERIALIZE_SERIALFIXEDARRAYLISTADAPTER_H_ */
-
-#endif /* SERIALFIXEDARRAYLISTADAPTER_H_ */

serialize/SerialLinkedListAdapter.h

@@ -1,32 +1,52 @@
-/**
+#ifndef FSFW_SERIALIZE_SERIALLINKEDLISTADAPTER_H_
- * @file	SerialLinkedListAdapter.h
+#define FSFW_SERIALIZE_SERIALLINKEDLISTADAPTER_H_
- * @brief	This file defines the SerialLinkedListAdapter class.
- * @date	22.07.2014
- * @author	baetz
- */
-#ifndef SERIALLINKEDLISTADAPTER_H_
-#define SERIALLINKEDLISTADAPTER_H_
 
 #include "../container/SinglyLinkedList.h"
 #include "SerializeAdapter.h"
 #include "SerializeElement.h"
 #include "SerializeIF.h"
-//This is where we need the SerializeAdapter!
 
-/**
+ /**
- * \ingroup serialize
+ * @brief  	Implement the conversion of object data to data streams
+ * 		   	or vice-versa, using linked lists.
+ * @details
+ * An alternative to the AutoSerializeAdapter functions
+ *   - All object members with a datatype are declared as
+ *     SerializeElement<element_type> members inside the class
+ *     implementing this adapter.
+ *   - The element type can also be a SerialBufferAdapter to
+ *     de-/serialize buffers.
+ *   - The element type can also be a SerialFixedArrayListAdapter to
+ *     de-/serialize buffers with a size header, which is scanned automatically.
+ *
+ * The sequence of objects is defined in the constructor by using
+ * the setStart and setNext functions.
+ *
+ * 1. The serialization process is done by instantiating the class and
+ *    calling serialize after all SerializeElement entries have been set by
+ *    using the constructor or setter functions. An additional size variable
+ *    can be supplied which is calculated/incremented automatically.
+ * 2. The deserialization process is done by instantiating the class and
+ *    supplying a buffer with the data which is converted into an object.
+ *    The size of data to serialize can be supplied and is
+ *    decremented in the function. Range checking is done internally.
+ * @author baetz
+ * @ingroup serialize
  */
 template<typename T, typename count_t = uint8_t>
 class SerialLinkedListAdapter: public SinglyLinkedList<T>, public SerializeIF {
 public:
+
 	SerialLinkedListAdapter(typename LinkedElement<T>::Iterator start,
 			bool printCount = false) :
 			SinglyLinkedList<T>(start), printCount(printCount) {
 	}
+
 	SerialLinkedListAdapter(LinkedElement<T>* first, bool printCount = false) :
 			SinglyLinkedList<T>(first), printCount(printCount) {
 
 	}
+
 	SerialLinkedListAdapter(bool printCount = false) :
 			SinglyLinkedList<T>(), printCount(printCount) {
 	}
@@ -49,13 +69,14 @@ public:
 			uint8_t** buffer, size_t* size, size_t maxSize,
 			Endianness streamEndianness) {
 		ReturnValue_t result = HasReturnvaluesIF::RETURN_OK;
-		while ((result == HasReturnvaluesIF::RETURN_OK) && (element != NULL)) {
+		while ((result == HasReturnvaluesIF::RETURN_OK) and (element != nullptr)) {
 			result = element->value->serialize(buffer, size, maxSize,
 					streamEndianness);
 			element = element->getNext();
 		}
 		return result;
 	}
+
 	virtual size_t getSerializedSize() const override {
 		if (printCount) {
 			return SerialLinkedListAdapter<T>::getSerializedSize()
@@ -64,32 +85,44 @@ public:
 			return getSerializedSize(SinglyLinkedList<T>::start);
 		}
 	}
+
 	static size_t getSerializedSize(const LinkedElement<T> *element) {
 		size_t size = 0;
-		while (element != NULL) {
+		while (element != nullptr) {
 			size += element->value->getSerializedSize();
 			element = element->getNext();
 		}
 		return size;
 	}
 
+
 	virtual ReturnValue_t deSerialize(const uint8_t** buffer, size_t* size,
 			Endianness streamEndianness) override {
-		return deSerialize(SinglyLinkedList<T>::start, buffer, size, streamEndianness);
+		return deSerialize(SinglyLinkedList<T>::start, buffer, size,
+				streamEndianness);
 	}
 
 	static ReturnValue_t deSerialize(LinkedElement<T>* element,
 			const uint8_t** buffer, size_t* size, Endianness streamEndianness) {
 		ReturnValue_t result = HasReturnvaluesIF::RETURN_OK;
-		while ((result == HasReturnvaluesIF::RETURN_OK) && (element != NULL)) {
+		while ((result == HasReturnvaluesIF::RETURN_OK) and (element != nullptr)) {
 			result = element->value->deSerialize(buffer, size, streamEndianness);
 			element = element->getNext();
 		}
 		return result;
 	}
 
-	bool printCount;
+	/**
+	 * Copying is forbidden by deleting the copy constructor and the copy
+	 * assignment operator because of the pointers to the linked list members.
+	 * Unless the child class implements an own copy constructor or
+	 * copy assignment operator, these operation will throw a compiler error.
+	 * @param
+	 */
+	SerialLinkedListAdapter(const SerialLinkedListAdapter &) = delete;
+	SerialLinkedListAdapter& operator=(const SerialLinkedListAdapter&) = delete;
 
+	bool printCount;
 };
 
-#endif /* SERIALLINKEDLISTADAPTER_H_ */
+#endif /* FSFW_SERIALIZE_SERIALLINKEDLISTADAPTER_H_ */

serialize/SerializeAdapter.h

@@ -7,17 +7,26 @@
 #include <cstddef>
 #include <type_traits>
 
-/**
+ /**
- * \ingroup serialize
+ * @brief These adapters provides an interface to use the SerializeIF functions
+ * 		  with arbitrary template objects to facilitate and simplify the
+ * 		  serialization of classes with different multiple different data types
+ * 		  into buffers and vice-versa.
+ * @details
+ * The correct serialization or deserialization function is chosen at
+ * compile time with template type deduction.
+ *
+ * @ingroup serialize
  */
-
 class SerializeAdapter {
 public:
 	/***
-	 * This function can be used to serialize a trivial copy-able type or a child of SerializeIF.
+	 * 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.
+	 * For objects of non trivial copy-able type this function is almost never
-	 * Instead helpers for specific types like SerialArrayListAdapter or SerialLinkedListAdapter is the right choice here.
+	 * 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.
@@ -86,7 +95,8 @@ private:
 	template<typename T>
 	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");
+				"If a type needs to be serialized it must be a child of "
+				"SerializeIF or trivially copy-able");
 	public:
 		static ReturnValue_t serialize(const T *object, uint8_t **buffer,
 				size_t *size, size_t max_size,
@@ -95,7 +105,8 @@ private:
 			if (size == nullptr) {
 				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
 			size_t newSize = sizeof(T) + *size;
 			if ((newSize <= max_size) and (newSize > *size)) {
 				T tmp;
@@ -111,7 +122,7 @@ private:
 					tmp = *object;
 					break;
 				}
-				memcpy(*buffer, &tmp, sizeof(T));
+				std::memcpy(*buffer, &tmp, sizeof(T));
 				*size += sizeof(T);
 				(*buffer) += sizeof(T);
 				return HasReturnvaluesIF::RETURN_OK;
@@ -125,7 +136,7 @@ private:
 			T tmp;
 			if (*size >= sizeof(T)) {
 				*size -= sizeof(T);
-				memcpy(&tmp, *buffer, sizeof(T));
+				std::memcpy(&tmp, *buffer, sizeof(T));
 				switch (streamEndianness) {
 				case SerializeIF::Endianness::BIG:
 					*object = EndianConverter::convertBigEndian<T>(tmp);

serialize/SerializeElement.h

@@ -1,12 +1,20 @@
-#ifndef SERIALIZEELEMENT_H_
+#ifndef FSFW_SERIALIZE_SERIALIZEELEMENT_H_
-#define SERIALIZEELEMENT_H_
+#define FSFW_SERIALIZE_SERIALIZEELEMENT_H_
 
-#include "../container/SinglyLinkedList.h"
 #include "SerializeAdapter.h"
+#include "../container/SinglyLinkedList.h"
 #include <utility>
 
 /**
- * \ingroup serialize
+ * @brief This class is used to mark datatypes for serialization with the
+ *        SerialLinkedListAdapter
+ * @details
+ * Used by declaring any arbitrary datatype with SerializeElement<T> myVariable,
+ * inside a SerialLinkedListAdapter implementation and setting the sequence
+ * of objects with setNext() and setStart().
+ * Serialization and Deserialization is then performed automatically in
+ * specified sequence order.
+ * @ingroup serialize
  */
 template<typename T>
 class SerializeElement: public SerializeIF, public LinkedElement<SerializeIF> {
@@ -19,7 +27,7 @@ public:
 	SerializeElement() :
 			LinkedElement<SerializeIF>(this) {
 	}
-	T entry;
+
 	ReturnValue_t serialize(uint8_t **buffer, size_t *size, size_t maxSize,
 			Endianness streamEndianness) const override {
 		return SerializeAdapter::serialize(&entry, buffer, size, maxSize,
@@ -35,6 +43,7 @@ public:
 		return SerializeAdapter::deSerialize(&entry, buffer, size,
 				streamEndianness);
 	}
+
 	operator T() {
 		return entry;
 	}
@@ -43,9 +52,12 @@ public:
 		entry = newValue;
 		return *this;
 	}
+
 	T* operator->() {
 		return &entry;
 	}
+
+	T entry;
 };
 
-#endif /* SERIALIZEELEMENT_H_ */
+#endif /* FSFW_SERIALIZE_SERIALIZEELEMENT_H_ */

serialize/SerializeIF.h

@@ -2,7 +2,7 @@
 #define FSFW_SERIALIZE_SERIALIZEIF_H_
 
 #include "../returnvalues/HasReturnvaluesIF.h"
-#include <stddef.h>
+#include <cstddef>
 
 /**
  * @defgroup serialize Serialization
@@ -10,7 +10,10 @@
  */
 
 /**
- * Translation of objects into data streams and from data streams.
+ * @brief 	Translation of objects into data streams and from data streams.
+ * @details
+ * Also provides options to convert from/to data with different endianness.
+ * variables.
  * @ingroup serialize
  */
 class SerializeIF {