From af52d1ffdaa3a8fa09a34a4c0e39785d9ade9ff9 Mon Sep 17 00:00:00 2001 From: Steffen Gaisser Date: Tue, 25 Aug 2020 14:14:58 +0200 Subject: [PATCH 1/4] Added some documentation in SerializeIF --- serialize/SerializeIF.h | 55 ++++++++++++++++++++++++++++++++++------- 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h index 9ed52d295..1f31d91ee 100644 --- a/serialize/SerializeIF.h +++ b/serialize/SerializeIF.h @@ -1,16 +1,16 @@ -#ifndef SERIALIZEIF_H_ -#define SERIALIZEIF_H_ +#ifndef FSFW_SERIALIZE_SERIALIZEIF_H_ +#define FSFW_SERIALIZE_SERIALIZEIF_H_ #include "../returnvalues/HasReturnvaluesIF.h" #include /** * \defgroup serialize Serialization - * Contains serialisation services. + * Contains serialization services. */ /** - * Translation of objects into data streams. + * Translation of objects into data streams and from data streams. * \ingroup serialize */ class SerializeIF { @@ -20,21 +20,58 @@ public: }; static const uint8_t INTERFACE_ID = CLASS_ID::SERIALIZE_IF; - static const ReturnValue_t BUFFER_TOO_SHORT = MAKE_RETURN_CODE(1); - static const ReturnValue_t STREAM_TOO_SHORT = MAKE_RETURN_CODE(2); - static const ReturnValue_t TOO_MANY_ELEMENTS = MAKE_RETURN_CODE(3); + static const ReturnValue_t BUFFER_TOO_SHORT = MAKE_RETURN_CODE(1); // !< The given buffer in serialize is too short + static const ReturnValue_t STREAM_TOO_SHORT = MAKE_RETURN_CODE(2); // !< The input stream in deSerialize is too short + static const ReturnValue_t TOO_MANY_ELEMENTS = MAKE_RETURN_CODE(3);// !< There are too many elements to be deSerialized virtual ~SerializeIF() { } - + /** + * Function to serialize the object into a buffer with maxSize at the current size. + * + * Implementations of this function must increase the size variable and move the buffer pointer. + * + * + * Custom implementations might use additional return values. + * + * @param buffer Buffer to serialize into, will be set to the current write location + * @param size Size that has been used in the buffer already, will be increase by the function + * @param maxSize Max size of the buffer. + * @param streamEndianness Endianness of the serialized data according to SerializeIF::Endianness + * @return + * - @¢ BUFFER_TOO_SHORT The given buffer in is too short + * - @c RETURN_FAILED Generic error + * - @c RETURN_OK Successful serialization + */ virtual ReturnValue_t serialize(uint8_t **buffer, size_t *size, size_t maxSize, Endianness streamEndianness) const = 0; + /** + * Gets the size of a object if it would be serialized in a buffer + * @return Size of serialized object + */ virtual size_t getSerializedSize() const = 0; + /** + * DeSerializes a object from a given buffer of given size. + * + * Buffer must be moved to the current read location by the implementation + * of this function. Size must be decreased by the implementation. + * + * Custom implementations might use additional return values. + * + * @param buffer Buffer to deSerialize from. Will be moved by the function. + * @param size Remaining Size of the buffer to read from. Will be decreased by function. + * @param 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 + */ virtual ReturnValue_t deSerialize(const uint8_t **buffer, size_t *size, Endianness streamEndianness) = 0; }; -#endif /* SERIALIZEIF_H_ */ +#endif /* FSFW_SERIALIZE_SERIALIZEIF_H_ */ From 6903a761ff3a185c1d79ada853cee975b77fdf57 Mon Sep 17 00:00:00 2001 From: Steffen Gaisser Date: Tue, 25 Aug 2020 14:23:59 +0200 Subject: [PATCH 2/4] Some corrections --- serialize/SerializeIF.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h index 1f31d91ee..3fb8b264f 100644 --- a/serialize/SerializeIF.h +++ b/serialize/SerializeIF.h @@ -21,8 +21,8 @@ public: static const uint8_t INTERFACE_ID = CLASS_ID::SERIALIZE_IF; static const ReturnValue_t BUFFER_TOO_SHORT = MAKE_RETURN_CODE(1); // !< The given buffer in serialize is too short - static const ReturnValue_t STREAM_TOO_SHORT = MAKE_RETURN_CODE(2); // !< The input stream in deSerialize is too short - static const ReturnValue_t TOO_MANY_ELEMENTS = MAKE_RETURN_CODE(3);// !< There are too many elements to be deSerialized + static const ReturnValue_t STREAM_TOO_SHORT = MAKE_RETURN_CODE(2); // !< The input stream in deserialize is too short + static const ReturnValue_t TOO_MANY_ELEMENTS = MAKE_RETURN_CODE(3);// !< There are too many elements to be deserialized virtual ~SerializeIF() { } @@ -53,7 +53,7 @@ public: virtual size_t getSerializedSize() const = 0; /** - * DeSerializes a object from a given buffer of given size. + * Deserializes a object from a given buffer of given size. * * Buffer must be moved to the current read location by the implementation * of this function. Size must be decreased by the implementation. @@ -61,7 +61,7 @@ public: * Custom implementations might use additional return values. * * @param buffer Buffer to deSerialize from. Will be moved by the function. - * @param size Remaining Size of the buffer to read from. Will be decreased by function. + * @param size Remaining size of the buffer to read from. Will be decreased by function. * @param streamEndianness Endianness as in according to SerializeIF::Endianness * @return * - @c STREAM_TOO_SHORT The input stream is too short to deSerialize the object From 1ae79ab99d53f324eccf7a715bb3aaa9ba665e66 Mon Sep 17 00:00:00 2001 From: Steffen Gaisser Date: Tue, 25 Aug 2020 15:06:53 +0200 Subject: [PATCH 3/4] Improvements of comments --- serialize/SerializeIF.h | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h index 3fb8b264f..2bb17154f 100644 --- a/serialize/SerializeIF.h +++ b/serialize/SerializeIF.h @@ -27,17 +27,21 @@ public: virtual ~SerializeIF() { } /** - * Function to serialize the object into a buffer with maxSize at the current size. + * @brief + * Function to serialize the object into a buffer with maxSize. Size represents the written amount. + * If a part of the buffer has been used already, size must be set to the used amount of bytes. * + * @details * Implementations of this function must increase the size variable and move the buffer pointer. - * + * MaxSize must be checked by implementations of this function + * and BUFFER_TOO_SHORT has to be returned if size would be larger than maxSize. * * Custom implementations might use additional return values. * - * @param buffer Buffer to serialize into, will be set to the current write location - * @param size Size that has been used in the buffer already, will be increase by the function - * @param maxSize Max size of the buffer. - * @param streamEndianness Endianness of the serialized data according to SerializeIF::Endianness + * @param[in/out] buffer Buffer to serialize into, will be set to the current write location + * @param[in/out] size Size that has been used in the buffer already, will be increased by the function + * @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 * @return * - @¢ BUFFER_TOO_SHORT The given buffer in is too short * - @c RETURN_FAILED Generic error @@ -47,22 +51,25 @@ public: size_t maxSize, Endianness streamEndianness) const = 0; /** - * Gets the size of a object if it would be serialized in a buffer + * Gets the size of a object if it would be serialized in a buffer.s * @return Size of serialized object */ virtual size_t getSerializedSize() const = 0; /** + * @brief * Deserializes a object from a given buffer of given size. * + * @details * Buffer must be moved to the current read location by the implementation * of this function. Size must be decreased by the implementation. + * Implementations are not allowed to alter the buffer as indicated by const pointer. * * Custom implementations might use additional return values. * - * @param buffer Buffer to deSerialize from. Will be moved by the function. - * @param size Remaining size of the buffer to read from. Will be decreased by function. - * @param streamEndianness Endianness as in according to SerializeIF::Endianness + * @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 From c0ed474373aef91fc12e2dc9b26bc9b8f4b8a4e4 Mon Sep 17 00:00:00 2001 From: gaisser Date: Tue, 1 Sep 2020 11:34:28 +0200 Subject: [PATCH 4/4] Update 'serialize/SerializeIF.h' --- serialize/SerializeIF.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/serialize/SerializeIF.h b/serialize/SerializeIF.h index 2bb17154f..7f9ea9dfd 100644 --- a/serialize/SerializeIF.h +++ b/serialize/SerializeIF.h @@ -5,13 +5,13 @@ #include /** - * \defgroup serialize Serialization + * @defgroup serialize Serialization * Contains serialization services. */ /** * Translation of objects into data streams and from data streams. - * \ingroup serialize + * @ingroup serialize */ class SerializeIF { public: @@ -51,7 +51,7 @@ public: size_t maxSize, Endianness streamEndianness) const = 0; /** - * Gets the size of a object if it would be serialized in a buffer.s + * Gets the size of a object if it would be serialized in a buffer * @return Size of serialized object */ virtual size_t getSerializedSize() const = 0;