byteStream.h

Go to the documentation of this file.

/*********************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*********************************************************************************/
 
#pragma once
 
//! \file byteStream.h
//! \brief Defines stream readers and writers for encoding and decoding messages from byte arrays
//! \ingroup vreRadarFxShared
 
#include "export.h"
 
#include <vlpi/entityIdentifier.h>
#include <vlpi/entityType.h>
#include <matrix/vlVector.h>
#include <matrix/vlTaitBryan.h>
#include <matrix/vlQuaternion.h>
 
#include <vector>
#include <string>
 
namespace makRadarFx
{
//! \brief Stream reader for decoding values from a byte array in little endian format
//!
//! This class reads and decodes various data types from a byte array,
//! assuming the data in the byte stream is in little endian format.
//! It provides methods for reading primitive types as well as common
//! complex data structures.
class RFX_DLL_SHARED DtStreamReader
{
public:
   //! \brief Constructor for stream reader
   //! \param buffer Pointer to the input byte array
   //! \param length Length of the input buffer in bytes
   //! \param makeCopy Whether to make a copy of the buffer (true) or use the original (false)
   //!
   //! Creates a new stream reader to work with the provided buffer
   DtStreamReader(unsigned char* buffer, int length, bool makeCopy = false);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources, including the buffer if it was copied
   virtual ~DtStreamReader();
 
   //! \name Value Reading Methods
   //! @{
   //! \brief Each method reads a value and advances the read position
 
   //! \brief Reads a boolean value
   //! \return The boolean value read from the stream
   virtual bool readBool();
 
   //! \brief Reads an 8-bit signed integer
   //! \return The 8-bit signed integer value read from the stream
   virtual char readInt8();
 
   //! \brief Reads an 8-bit unsigned integer
   //! \return The 8-bit unsigned integer value read from the stream
   virtual unsigned char readUInt8();
 
   //! \brief Reads a 16-bit signed integer
   //! \return The 16-bit signed integer value read from the stream
   virtual short readInt16();
 
   //! \brief Reads a 16-bit unsigned integer
   //! \return The 16-bit unsigned integer value read from the stream
   virtual unsigned short readUInt16();
 
   //! \brief Reads a 32-bit signed integer
   //! \return The 32-bit signed integer value read from the stream
   virtual int readInt32();
 
   //! \brief Reads a 32-bit unsigned integer
   //! \return The 32-bit unsigned integer value read from the stream
   virtual unsigned readUInt32();
 
   //! \brief Reads a 64-bit signed integer
   //! \return The 64-bit signed integer value read from the stream
   virtual long long readInt64();
 
   //! \brief Reads a 64-bit unsigned integer
   //! \return The 64-bit unsigned integer value read from the stream
   virtual unsigned long long readUInt64();
 
   //! \brief Reads a 32-bit floating point value
   //! \return The 32-bit float value read from the stream
   virtual float readSingle();
 
   //! \brief Reads a 64-bit floating point value
   //! \return The 64-bit double value read from the stream
   virtual double readDouble();
 
   //! \brief Reads a string
   //! \return The string value read from the stream
   virtual std::string readString();
 
   //! \brief Reads a 3D vector
   //! \return The vector value read from the stream
   virtual DtVector readVector();
 
   //! \brief Reads a Tait-Bryan angle set
   //! \return The Tait-Bryan angles read from the stream
   virtual DtTaitBryan readTaitBryan();
 
   //! \brief Reads a quaternion
   //! \return The quaternion value read from the stream
   DtQuaternion readQuaternion();
 
   //! \brief Reads an entity identifier
   //! \return The entity identifier read from the stream
   DtEntityIdentifier readEntityId();
 
   //! \brief Reads an entity type
   //! \return The entity type read from the stream
   DtEntityType readEntityType();
 
   //! \brief Allocates and reads bytes into a new buffer
   //! \param length Number of bytes to read
   //! \return Pointer to a newly allocated buffer containing the read bytes
   //!
   //! This method allocates a new byte array and copies data into it
   unsigned char* readBytes(int length);
 
   //! \brief Reads bytes into a supplied buffer
   //! \param buffer Pointer to the destination buffer
   //! \param length Number of bytes to read
   //!
   //! This reads from the byte stream into a supplied buffer
   virtual void readBytes(unsigned char* buffer, int length);
 
   //@}
 
protected:
   //! \brief Determines the size of a string from a variable length encoded integer
   //! \return The decoded size of the following string
   int decodeStringSize();
 
   //! \brief Pointer to the beginning of the buffer
   unsigned char* myBuffer;
 
   //! \brief Current read position within the buffer
   unsigned char* myReadHead;
 
   //! \brief Total length of the buffer in bytes
   int myLength;
 
   //! \brief Flag indicating if the buffer should be deleted on destruction
   bool myShouldDelete;
};
 
//! \brief Stream writer for encoding values into a byte array in little endian format
//!
//! This class writes and encodes various data types into a byte array
//! in little endian format. It provides methods for writing primitive types
//! as well as common complex data structures.
class RFX_DLL_SHARED DtStreamWriter
{
public:
   //! \brief Constructor that creates an internal buffer
   //! \param length Size of the internal buffer to create
   //!
   //! Creates a new stream writer with an internal buffer of the specified size.
   //! Care must be taken to allocate enough space for all the intended writes.
   DtStreamWriter(int length);
 
   //! \brief Constructor that uses an existing buffer
   //! \param buffer Pointer to the buffer to write to
   //! \param length Size of the buffer in bytes
   //!
   //! Creates a new stream writer using the provided buffer.
   //! Care must be taken to ensure the buffer has enough space for all writes.
   DtStreamWriter(unsigned char* buffer, int length);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources, including the buffer if it was allocated internally
   virtual ~DtStreamWriter();
 
   //! \name Buffer Access Methods
   //! @{
 
   //! \brief Gets a pointer to the internal buffer
   //! \return Pointer to the internal buffer
   virtual unsigned char* buffer();
 
   //! \brief Gets the current write position as a length
   //! \return Number of bytes written to the buffer so far
   virtual int length();
 
   //! @}
 
   //! \name Value Writing Methods
   //! @{
   //! \brief Each method writes a value and advances the write position
 
   //! \brief Writes a boolean value
   //! \param b Boolean value to write
   virtual void writeBool(bool b);
 
   //! \brief Writes an 8-bit signed integer
   //! \param num Value to write
   virtual void writeInt8(char num);
 
   //! \brief Writes an 8-bit unsigned integer
   //! \param num Value to write
   virtual void writeUInt8(unsigned char num);
 
   //! \brief Writes a 16-bit signed integer
   //! \param num Value to write
   virtual void writeInt16(short num);
 
   //! \brief Writes a 16-bit unsigned integer
   //! \param num Value to write
   virtual void writeUInt16(unsigned short num);
 
   //! \brief Writes a 32-bit signed integer
   //! \param num Value to write
   virtual void writeInt32(int num);
 
   //! \brief Writes a 32-bit unsigned integer
   //! \param num Value to write
   virtual void writeUInt32(unsigned int num);
 
   //! \brief Writes a 64-bit signed integer
   //! \param num Value to write
   virtual void writeInt64(long long num);
 
   //! \brief Writes a 64-bit unsigned integer
   //! \param num Value to write
   virtual void writeUInt64(unsigned long long num);
 
   //! \brief Writes a 32-bit floating point value
   //! \param num Value to write
   virtual void writeSingle(float num);
 
   //! \brief Writes a 64-bit floating point value
   //! \param num Value to write
   virtual void writeDouble(double num);
 
   //! \brief Writes a string
   //! \param str String value to write
   virtual void writeString(std::string& str);
 
   //! \brief Writes a 3D vector
   //! \param vec Vector to write
   virtual void writeVector(DtVector& vec);
 
   //! \brief Writes a Tait-Bryan angle set
   //! \param tb Tait-Bryan angles to write
   virtual void writeTaitBryan(DtTaitBryan& tb);
 
   //! \brief Writes a quaternion
   //! \param q Quaternion to write
   virtual void writeQuaternion(const DtQuaternion& q);
 
   //! \brief Writes an entity identifier
   //! \param id Entity identifier to write
   virtual void writeEntityId(const DtEntityIdentifier& id);
 
   //! \brief Writes an entity type
   //! \param type Entity type to write
   virtual void writeEntityType(const DtEntityType& type);
 
   //! \brief Writes raw bytes
   //! \param buffer Pointer to the source buffer
   //! \param length Number of bytes to write
   virtual void writeBytes(unsigned char* buffer, int length);
   //@}
 
protected:
   //! \brief Encodes the size of the string as a variable length integer
   //! \param size Size to encode
   void encodeStringSize(int size);
 
   //! \brief Pointer to the beginning of the buffer
   unsigned char* myBuffer;
 
   //! \brief Current write position within the buffer
   unsigned char* myWriteHead;
 
   //! \brief Total length of the buffer in bytes
   int myLength;
 
   //! \brief Flag indicating if the buffer should be deleted on destruction
   bool myShouldDelete;
};
 
//! \brief Stream reader for decoding values from a byte array in big endian format
//!
//! This class extends DtStreamReader to read and decode data from a byte array
//! where the data is stored in big endian format. It overrides the methods
//! that need byte swapping to convert from big endian to the system's native format.
class RFX_DLL_SHARED DtBigEndianStreamReader : public DtStreamReader
{
public:
   //! \brief Constructor for big endian stream reader
   //! \param buffer Pointer to the input byte array
   //! \param length Length of the input buffer in bytes
   //! \param makeCopy Whether to make a copy of the buffer (true) or use the original (false)
   //!
   //! Creates a new big endian stream reader to work with the provided buffer
   DtBigEndianStreamReader(unsigned char* buffer, int length, bool makeCopy = false);
 
   //! \brief Virtual destructor
   virtual ~DtBigEndianStreamReader();
 
   //! \name Big Endian Value Reading Methods
   //! @{
   //! \brief Each method reads a big endian value and advances the read position
 
   //! \brief Reads a 16-bit signed integer in big endian format
   //! \return The 16-bit signed integer value read from the stream
   virtual short readInt16();
 
   //! \brief Reads a 16-bit unsigned integer in big endian format
   //! \return The 16-bit unsigned integer value read from the stream
   virtual unsigned short readUInt16();
 
   //! \brief Reads a 32-bit signed integer in big endian format
   //! \return The 32-bit signed integer value read from the stream
   virtual int readInt32();
 
   //! \brief Reads a 32-bit unsigned integer in big endian format
   //! \return The 32-bit unsigned integer value read from the stream
   virtual unsigned readUInt32();
 
   //! \brief Reads a 64-bit signed integer in big endian format
   //! \return The 64-bit signed integer value read from the stream
   virtual long long readInt64();
 
   //! \brief Reads a 64-bit unsigned integer in big endian format
   //! \return The 64-bit unsigned integer value read from the stream
   virtual unsigned long long readUInt64();
 
   //! \brief Reads a 32-bit floating point value in big endian format
   //! \return The 32-bit float value read from the stream
   virtual float readSingle();
 
   //! \brief Reads a 64-bit floating point value in big endian format
   //! \return The 64-bit double value read from the stream
   virtual double readDouble();
   //@}
 
protected:
};
 
//! \brief Stream writer for encoding values into a byte array in big endian format
//!
//! This class extends DtStreamWriter to write and encode data into a byte array
//! in big endian format. It overrides the methods that need byte swapping
//! to convert from the system's native format to big endian.
class RFX_DLL_SHARED DtBigEndianStreamWriter : public DtStreamWriter
{
public:
   //! \brief Constructor that creates an internal buffer
   //! \param length Size of the internal buffer to create
   //!
   //! Creates a new big endian stream writer with an internal buffer of the specified size.
   //! Care must be taken to allocate enough space for all the intended writes.
   DtBigEndianStreamWriter(int length);
 
   //! \brief Constructor that uses an existing buffer
   //! \param buffer Pointer to the buffer to write to
   //! \param length Size of the buffer in bytes
   //!
   //! Creates a new big endian stream writer using the provided buffer.
   //! Care must be taken to ensure the buffer has enough space for all writes.
   DtBigEndianStreamWriter(unsigned char* buffer, int length);
 
   //! \brief Virtual destructor
   virtual ~DtBigEndianStreamWriter();
 
   //! \name Big Endian Value Writing Methods
   //! @{
   //! \brief Each method writes a value in big endian format and advances the write position
 
   //! \brief Writes a 16-bit signed integer in big endian format
   //! \param num Value to write
   void writeInt16(short num);
 
   //! \brief Writes a 16-bit unsigned integer in big endian format
   //! \param num Value to write
   void writeUInt16(unsigned short num);
 
   //! \brief Writes a 32-bit signed integer in big endian format
   //! \param num Value to write
   void writeInt32(int num);
 
   //! \brief Writes a 32-bit unsigned integer in big endian format
   //! \param num Value to write
   void writeUInt32(unsigned int num);
 
   //! \brief Writes a 64-bit signed integer in big endian format
   //! \param num Value to write
   void writeInt64(long long num);
 
   //! \brief Writes a 64-bit unsigned integer in big endian format
   //! \param num Value to write
   void writeUInt64(unsigned long long num);
 
   //! \brief Writes a 32-bit floating point value in big endian format
   //! \param num Value to write
   void writeSingle(float num);
 
   //! \brief Writes a 64-bit floating point value in big endian format
   //! \param num Value to write
   void writeDouble(double num);
   //@}
 
protected:
};
 
//! \brief Calculates the size in bytes of the string when encoded
//! \param str String to calculate the encoded size for
//! \return Size in bytes that the string will occupy when encoded
//!
//! This function calculates the total number of bytes that will be
//! required to encode the given string, including the size prefix.
RFX_DLL_SHARED int DtEncodedStringLength(std::string str);
} // namespace makRadarFx