vreMessage.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
#pragma once
 
//! \file vreMessage.h
//! \ingroup managedInterface
//! \brief Defines the base class for all VREngage messages
//!
//! This file contains the DtVreMessage abstract base class which serves as the foundation
//! for all messages in the VREngage messaging system. It provides core functionality for
//! message serialization/deserialization, identification, and lifecycle management.
//! Messages are used for communication between components both within a single
//! application instance and across the network.
#include "vreMessageManager/export.h"
#include "vreMessageManager/vreMessageId.h"
#include "vreUtil/utilFunctions.h"
#include "vreUtil/byteStream.h"
#include "vreutil/delegate.h"
 
#include <string>
#include <memory>
 
namespace makVre
{
//! \brief Enumeration of possible message handling results
//!
//! These values are returned by message handlers to indicate how a message was processed
//! and whether further processing should occur.
enum DtVreMessageResult
{
   IGNORED, //!< The handler did not process the message; continue processing
   HANDLED, //!< The handler processed the message; continue processing
   EATEN    //!< The handler processed the message; stop further processing
};
 
//! \brief Abstract base class for all VREngage messages
//!
//! This class serves as the foundation for all messages in the VREngage messaging system.
//! It provides core functionality for message serialization/deserialization, identification,
//! and lifecycle management. All concrete message types must inherit from this class and
//! implement the pure virtual methods.
//!
//! Messages contain a type identifier, serialization/deserialization mechanisms, versioning,
//! and features to support network distribution including originating application ID tracking
//! to prevent message loops.
class MESSAGEMANAGER_DLL DtVreMessage
{
public:
   //! \brief Default constructor
   //!
   //! Initializes a new message with zero delay, zero application ID,
   //! and version 1.
   DtVreMessage();
 
   //! \brief Virtual destructor
   //!
   //! Ensures proper cleanup of derived message classes.
   virtual ~DtVreMessage();
 
   //! \brief Gets the string name of the message type
   //! \return Reference to the message type string
   //!
   //! This pure virtual method must be implemented by derived classes to
   //! return a unique string identifier for the message type. This is used
   //! for message routing and identification.
   virtual const std::string& type() const = 0;
 
   //! \brief Gets the message ID object
   //! \return Reference to the message ID object
   //!
   //! This pure virtual method must be implemented by derived classes to
   //! return a unique identifier object for the message. The message ID
   //! contains both the type name and a hash value for efficient routing.
   virtual const DtVreMessageId& messageId() const = 0;
 
   //! \brief Encodes the message as an array of bytes and returns the bytes
   //! \return Newly allocated buffer containing the serialized message
   //!
   //! This method serializes the message into a newly allocated buffer and
   //! returns a pointer to that buffer. The caller is responsible for deleting
   //! the returned buffer when it is no longer needed.
   //!
   //! \note This method allocates memory that must be freed by the caller
   virtual char* encode();
 
   //! \brief Encodes the message into the given buffer of bytes
   //! \param buffer Pointer to the buffer to write into
   //! \param bufferSize Size of the buffer in bytes
   //!
   //! This method serializes the message into the provided buffer. The buffer
   //! must be at least as large as messageSize() bytes.
   //!
   //! \note This method assumes bufferSize >= messageSize()
   virtual void encode(char* buffer, int bufferSize);
 
   //! \brief Static decode function pattern for derived classes
   //! \note Each derived class must implement a static decode function with the signature:
   //! \code
   //! static DtVreMessage* decode(unsigned char* buffer, int length);
   //! \endcode
   //! This function is used by the message factory to create messages from raw data.
 
   //! \brief Gets the total size of the serialized message in bytes
   //! \return Size of the message in bytes
   //!
   //! This method calculates the total size of the message when serialized,
   //! including the base message header (message size, type hash, application ID,
   //! version, and delay) and any data added by derived classes.
   //!
   //! Derived classes should override this method to include their own data size
   //! while calling the base class implementation.
   virtual int messageSize() const;
 
   //! \brief Gets the ID of the application that created this message
   //! \return Application ID value
   //!
   //! This method returns the unique identifier of the application instance
   //! that created this message. It is used by network forwarders to prevent
   //! message loops when distributing messages across networks.
   //!
   //! The ID defaults to 0 when a new message is created and is set by the
   //! network forwarder when sending a message.
   virtual const UInt64 originatingApplicationId() const;
 
   //! \brief Sets the ID of the application that created this message
   //! \param appId The application ID to set
   //!
   //! This method sets the unique identifier of the application instance
   //! that created this message. It is primarily used by network forwarders
   //! to tag outgoing messages with the local application ID.
   virtual void setOriginatingApplicationId(UInt64 appId);
 
   //! \brief Sets a delay in seconds before the message is dispatched
   //! \param delay Delay time in seconds
   //!
   //! This method sets a delay time that must elapse before the message
   //! is processed by the message manager. It allows for scheduled message
   //! delivery.
   //!
   //! \note This is an internal API, not to be called by users directly
   virtual void setDelay(double delay);
 
   //! \brief Checks if the message has remaining delay time
   //! \return True if there is any delay remaining, false otherwise
   //!
   //! This method checks if the message still has remaining delay time
   //! before it should be processed.
   //!
   //! \note This is an internal API, not to be called by users directly
   virtual bool isDelayed();
 
   //! \brief Reduces the remaining delay time
   //! \param dt Time in seconds to subtract from the delay
   //!
   //! This method reduces the remaining delay time by the specified amount.
   //! It is called by the message manager during each update cycle to track
   //! delayed messages.
   //!
   //! \note This is an internal API, not to be called by users directly
   virtual void reduceDelay(double dt);
 
   //! \brief Gets the version number of this message
   //! \return Version number
   //!
   //! This method returns the version number of the message, which can be
   //! used for backward compatibility and migration between different versions
   //! of the messaging system. The version number may be a bitfield containing
   //! various pieces of information.
   virtual const UInt64 versionNumber() const;
 
protected:
   //! \brief Serializes the message to a stream writer
   //! \param writer Reference to the stream writer
   //!
   //! This method writes the message header fields to the stream writer.
   //! Derived classes should override this method to add their own fields
   //! while calling the base class implementation.
   virtual void serialize(DtStreamWriter& writer) const;
 
   //! \brief Deserializes the message from a stream reader
   //! \param reader Reference to the stream reader
   //!
   //! This method reads the message header fields from the stream reader.
   //! Derived classes should override this method to read their own fields
   //! while calling the base class implementation.
   virtual void deserialize(DtStreamReader& reader);
 
   //! \brief Delay time in seconds before the message should be processed
   double myDelay;
 
   //! \brief ID of the application that created this message
   UInt64 myApplicationId;
 
   //! \brief Version number of this message
   UInt64 myVersion;
};
 
//! \brief Shared pointer type for DtVreMessage objects
//!
//! This type defines a shared pointer to a DtVreMessage object, providing
//! automatic memory management for messages.
using DtVreMessagePtr = std::shared_ptr<DtVreMessage>;
 
//! \brief Delegate type for message handler callbacks
//!
//! This type defines a delegate that takes a DtVreMessage pointer and
//! returns a DtVreMessageResult value. It is used to register message
//! handlers with the message manager.
using DtVreMessageDelegate = DtDelegate<DtVreMessageResult, DtVreMessage*>;
 
} // namespace makVre