dle encoder doc added

globalfunctions/DleEncoder.cpp

@@ -1,95 +1,124 @@
-#include "DleEncoder.h"
+#include "../globalfunctions/DleEncoder.h"
 
-DleEncoder::DleEncoder() {
+DleEncoder::DleEncoder() {}
-}
 
-DleEncoder::~DleEncoder() {
+DleEncoder::~DleEncoder() {}
+
+ReturnValue_t DleEncoder::encode(const uint8_t* sourceStream,
+		size_t sourceLen, uint8_t* destStream, size_t maxDestLen,
+		size_t* encodedLen, bool addStxEtx) {
+	if (maxDestLen < 2) {
+		return STREAM_TOO_SHORT;
+	}
+	size_t encodedIndex = 0, sourceIndex = 0;
+	uint8_t nextByte;
+	if (addStxEtx) {
+		destStream[0] = STX_CHAR;
+		++encodedIndex;
+	}
+
+	while (encodedIndex < maxDestLen and sourceIndex < sourceLen)
+	{
+		nextByte = sourceStream[sourceIndex];
+		// STX, ETX and CR characters in the stream need to be escaped with DLE
+		if (nextByte == STX_CHAR or nextByte == ETX_CHAR or nextByte == CARRIAGE_RETURN) {
+			if (encodedIndex + 1 >= maxDestLen) {
+				return STREAM_TOO_SHORT;
+			}
+			else {
+				destStream[encodedIndex] = DLE_CHAR;
+				++encodedIndex;
+				/* Escaped byte will be actual byte + 0x40. This prevents
+				 * STX, ETX, and carriage return characters from appearing
+				 * in the encoded data stream at all, so when polling an
+				 * encoded stream, the transmission can be stopped at ETX.
+				 * 0x40 was chosen at random with special requirements:
+				 *  - Prevent going from one control char to another
+				 *  - Prevent overflow for common characters */
+				destStream[encodedIndex] = nextByte + 0x40;
+			}
+		}
+		// DLE characters are simply escaped with DLE.
+		else if (nextByte == DLE_CHAR) {
+			if (encodedIndex + 1 >= maxDestLen) {
+			    return STREAM_TOO_SHORT;
+			}
+			else {
+				destStream[encodedIndex] = DLE_CHAR;
+				++encodedIndex;
+				destStream[encodedIndex] = DLE_CHAR;
+			}
+		}
+		else {
+			destStream[encodedIndex] = nextByte;
+		}
+		++encodedIndex;
+		++sourceIndex;
+	}
+
+	if (sourceIndex == sourceLen and encodedIndex < maxDestLen) {
+		if (addStxEtx) {
+			destStream[encodedIndex] = ETX_CHAR;
+			++encodedIndex;
+		}
+		*encodedLen = encodedIndex;
+		return RETURN_OK;
+	}
+	else {
+		return STREAM_TOO_SHORT;
+	}
 }
 
 ReturnValue_t DleEncoder::decode(const uint8_t *sourceStream,
-		uint32_t sourceStreamLen, uint32_t *readLen, uint8_t *destStream,
+		size_t sourceStreamLen, size_t *readLen, uint8_t *destStream,
-		uint32_t maxDestStreamlen, uint32_t *decodedLen) {
+		size_t maxDestStreamlen, size_t *decodedLen) {
-	uint32_t encodedIndex = 0, decodedIndex = 0;
+	size_t encodedIndex = 0, decodedIndex = 0;
 	uint8_t nextByte;
-	if (*sourceStream != STX) {
+	if (*sourceStream != STX_CHAR) {
-		return RETURN_FAILED;
+		return DECODING_ERROR;
 	}
 	++encodedIndex;
+
 	while ((encodedIndex < sourceStreamLen) && (decodedIndex < maxDestStreamlen)
-			&& (sourceStream[encodedIndex] != ETX)
+			&& (sourceStream[encodedIndex] != ETX_CHAR)
-			&& (sourceStream[encodedIndex] != STX)) {
+			&& (sourceStream[encodedIndex] != STX_CHAR)) {
-		if (sourceStream[encodedIndex] == DLE) {
+		if (sourceStream[encodedIndex] == DLE_CHAR) {
 			nextByte = sourceStream[encodedIndex + 1];
-			if (nextByte == 0x10) {
+			// The next byte is a DLE character that was escaped by another
+			// DLE character, so we can write it to the destination stream.
+			if (nextByte == DLE_CHAR) {
 				destStream[decodedIndex] = nextByte;
-			} else {
+			}
-				if ((nextByte == 0x42) || (nextByte == 0x43)
+			else {
-						|| (nextByte == 0x4D)) {
+			    /* The next byte is a STX, DTX or 0x0D character which
+			     * was escaped by a DLE character. The actual byte was
+				 * also encoded by adding + 0x40 to preven having control chars,
+				 * in the stream at all, so we convert it back. */
+				if (nextByte == 0x42 or nextByte == 0x43 or nextByte == 0x4D) {
 					destStream[decodedIndex] = nextByte - 0x40;
-				} else {
+				}
-					return RETURN_FAILED;
+				else {
+				    return DECODING_ERROR;
 				}
 			}
 			++encodedIndex;
-		} else {
+		}
+		else {
 			destStream[decodedIndex] = sourceStream[encodedIndex];
 		}
+
 		++encodedIndex;
 		++decodedIndex;
 	}
-	if (sourceStream[encodedIndex] != ETX) {
+
-		return RETURN_FAILED;
+	if (sourceStream[encodedIndex] != ETX_CHAR) {
-	} else {
+		*readLen = ++encodedIndex;
+		return DECODING_ERROR;
+	}
+	else {
 		*readLen = ++encodedIndex;
 		*decodedLen = decodedIndex;
 		return RETURN_OK;
 	}
 }
 
-ReturnValue_t DleEncoder::encode(const uint8_t* sourceStream,
-		uint32_t sourceLen, uint8_t* destStream, uint32_t maxDestLen,
-		uint32_t* encodedLen, bool addStxEtx) {
-	if (maxDestLen < 2) {
-		return RETURN_FAILED;
-	}
-	uint32_t encodedIndex = 0, sourceIndex = 0;
-	uint8_t nextByte;
-	if (addStxEtx) {
-		destStream[0] = STX;
-		++encodedIndex;
-	}
-	while ((encodedIndex < maxDestLen) && (sourceIndex < sourceLen)) {
-		nextByte = sourceStream[sourceIndex];
-		if ((nextByte == STX) || (nextByte == ETX) || (nextByte == 0x0D)) {
-			if (encodedIndex + 1 >= maxDestLen) {
-				return RETURN_FAILED;
-			} else {
-				destStream[encodedIndex] = DLE;
-				++encodedIndex;
-				destStream[encodedIndex] = nextByte + 0x40;
-			}
-		} else if (nextByte == DLE) {
-			if (encodedIndex + 1 >= maxDestLen) {
-				return RETURN_FAILED;
-			} else {
-				destStream[encodedIndex] = DLE;
-				++encodedIndex;
-				destStream[encodedIndex] = DLE;
-			}
-		} else {
-			destStream[encodedIndex] = nextByte;
-		}
-		++encodedIndex;
-		++sourceIndex;
-	}
-	if ((sourceIndex == sourceLen) && (encodedIndex < maxDestLen)) {
-		if (addStxEtx) {
-			destStream[encodedIndex] = ETX;
-			++encodedIndex;
-		}
-		*encodedLen = encodedIndex;
-		return RETURN_OK;
-	} else {
-		return RETURN_FAILED;
-	}
-}

globalfunctions/DleEncoder.h

@@ -1,25 +1,79 @@
-#ifndef DLEENCODER_H_
+#ifndef FRAMEWORK_GLOBALFUNCTIONS_DLEENCODER_H_
-#define DLEENCODER_H_
+#define FRAMEWORK_GLOBALFUNCTIONS_DLEENCODER_H_
 
 #include "../returnvalues/HasReturnvaluesIF.h"
+#include <cstddef>
 
+/**
+ * @brief   This DLE Encoder (Data Link Encoder) can be used to encode and
+ *          decode arbitrary data with ASCII control characters
+ * @details
+ * List of control codes:
+ * https://en.wikipedia.org/wiki/C0_and_C1_control_codes
+ *
+ * This encoder can be used to achieve a basic transport layer when using
+ * char based transmission systems.
+ * The passed source strean is converted into a encoded stream by adding
+ * a STX marker at the start of the stream and an ETX marker at the end of
+ * the stream. Any STX, ETX, DLE and CR occurences in the source stream are
+ * escaped by a DLE character. The encoder also replaces escaped control chars
+ * by another char, so STX, ETX and CR should not appear anywhere in the actual
+ * encoded data stream.
+ *
+ * When using a strictly char based reception of packets enoded with DLE,
+ * STX can be used to notify a reader that actual data will start to arrive
+ * while ETX can be used to notify the reader that the data has ended.
+ */
 class DleEncoder: public HasReturnvaluesIF {
 private:
 	DleEncoder();
 	virtual ~DleEncoder();
 
 public:
-	static const uint8_t STX = 0x02;
+	static constexpr uint8_t INTERFACE_ID = CLASS_ID::DLE_ENCODER;
-	static const uint8_t ETX = 0x03;
+	static constexpr ReturnValue_t STREAM_TOO_SHORT = MAKE_RETURN_CODE(0x01);
-	static const uint8_t DLE = 0x10;
+	static constexpr ReturnValue_t DECODING_ERROR = MAKE_RETURN_CODE(0x02);
 
+	//! Start Of Text character. First character is encoded stream
+	static constexpr uint8_t STX_CHAR = 0x02;
+	//! End Of Text character. Last character in encoded stream
+	static constexpr uint8_t ETX_CHAR = 0x03;
+	//! Data Link Escape character. Used to escape STX, ETX and DLE occurences
+	//! in the source stream.
+	static constexpr uint8_t DLE_CHAR = 0x10;
+	static constexpr uint8_t CARRIAGE_RETURN = 0x0D;
+
+    /**
+     * Encodes the give data stream by preceding it with the STX marker
+     * and ending it with an ETX marker. STX, ETX and DLE characters inside
+     * the stream are escaped by DLE characters and also replaced by adding
+     * 0x40 (which is reverted in the decoing process).
+     * @param sourceStream
+     * @param sourceLen
+     * @param destStream
+     * @param maxDestLen
+     * @param encodedLen
+     * @param addStxEtx
+     * Adding STX and ETX can be omitted, if they are added manually.
+     * @return
+     */
+    static ReturnValue_t encode(const uint8_t *sourceStream, size_t sourceLen,
+            uint8_t *destStream, size_t maxDestLen, size_t *encodedLen,
+            bool addStxEtx = true);
+
+    /**
+     * Converts an encoded stream back.
+     * @param sourceStream
+     * @param sourceStreamLen
+     * @param readLen
+     * @param destStream
+     * @param maxDestStreamlen
+     * @param decodedLen
+     * @return
+     */
 	static ReturnValue_t decode(const uint8_t *sourceStream,
-			uint32_t sourceStreamLen, uint32_t *readLen, uint8_t *destStream,
+			size_t sourceStreamLen, size_t *readLen, uint8_t *destStream,
-			uint32_t maxDestStreamlen, uint32_t *decodedLen);
+			size_t maxDestStreamlen, size_t *decodedLen);
-
-	static ReturnValue_t encode(const uint8_t *sourceStream, uint32_t sourceLen,
-			uint8_t *destStream, uint32_t maxDestLen, uint32_t *encodedLen,
-			bool addStxEtx = true);
 };
 
-#endif /* DLEENCODER_H_ */
+#endif /* FRAMEWORK_GLOBALFUNCTIONS_DLEENCODER_H_ */