networkForwarder.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file networkForwarder.h
//! \brief Defines base class for VREngage message network forwarding
//!
//! This file contains the DtNetworkForwarder abstract base class and DtVreMessageBundle
//! utility class for VREngage message forwarding across networks. The network forwarder
//! handles bundling of messages for efficient transmission and provides mechanisms for
//! forwarding specific message types. Derived classes implement the actual network
//! transport specifics.
 
#pragma once
 
#include "vreMessageManager/export.h"
#include "vreMessageManager/vreMessageListenerTree.h"
#include "vreMessageManager/vreMessage.h"
 
#include <string>
 
namespace makVre
{
class DtVreMessageFactory;
 
//! \brief Utility class for bundling multiple messages into a single network packet
//!
//! This class provides a buffer for bundling multiple VREngage messages together
//! for efficient network transmission. It manages a resizable buffer and provides
//! methods for adding messages, checking capacity, and tracking buffer usage.
struct MESSAGEMANAGER_DLL DtVreMessageBundle
{
   //! \brief Pointer to the buffer containing bundled messages
   char* myBuffer;
 
   //! \brief Current write position in the buffer
   char* myWriteHead;
 
   //! \brief Maximum size of the buffer in bytes
   int myMaxSize;
 
   //! \brief Constructor
   //! \param maxSize Maximum size of the buffer in bytes
   //!
   //! Allocates a new buffer of the specified size for bundling messages.
   DtVreMessageBundle(int maxSize);
 
   //! \brief Destructor
   //!
   //! Deallocates the buffer memory.
   ~DtVreMessageBundle();
 
   //! \brief Resets the write position to the beginning of the buffer
   //!
   //! Allows the buffer to be reused after its contents have been sent.
   void reset();
 
   //! \brief Gets the number of bytes currently used in the buffer
   //! \return Number of bytes used
   int used();
 
   //! \brief Gets the number of bytes remaining in the buffer
   //! \return Number of bytes remaining
   int bufferRemaining();
 
   //! \brief Checks if a message of the specified size can be added to the buffer
   //! \param size Size of the message in bytes
   //! \return True if the message can be added, false otherwise
   bool canAdd(int size);
 
   //! \brief Adds a message to the buffer
   //! \param data Pointer to the message data
   //! \param size Size of the message in bytes
   //!
   //! Copies the message data into the buffer and advances the write position.
   void add(char* data, int size);
};
 
//! \brief Abstract base class for network forwarding of VREngage messages
//!
//! This class provides the foundation for forwarding VREngage messages across
//! networks. It handles message bundling for efficient transmission and provides
//! mechanisms for forwarding specific message types. Derived classes implement
//! the actual network transport specifics by overriding the pure virtual flush()
//! method and optionally the netSendMessage() method.
class MESSAGEMANAGER_DLL DtNetworkForwarder
{
public:
   //! \brief Constructor
   //! \param factory Pointer to the message factory for creating messages from raw data
   //!
   //! Initializes a new network forwarder with the specified message factory.
   //! The message factory is used to create messages from incoming raw data.
   //! This constructor also initializes the first message bundle for outgoing messages.
   DtNetworkForwarder(DtVreMessageFactory* factory);
 
   //! \brief Virtual destructor
   //!
   //! Calls disable() to unregister message handlers and performs cleanup.
   virtual ~DtNetworkForwarder();
 
   //! \brief Flushes bundled messages to the network
   //!
   //! This pure virtual method must be implemented by derived classes to send
   //! accumulated message bundles over the network. Because messages are bundled
   //! for efficiency, this method should be called once per frame to ensure
   //! timely delivery of messages.
   //!
   //! \note This must be called once per frame to ensure messages are transmitted
   virtual void flush() = 0;
 
   //! \brief Enables the network forwarder
   //! \return True if the forwarder was successfully enabled
   //!
   //! This method enables the network forwarder by registering message handlers
   //! for forwarding control messages. When enabled, the forwarder will process
   //! incoming control messages and forward outgoing messages of registered types.
   //! It also initializes the unique ID for this forwarder instance.
   virtual bool enable();
 
   //! \brief Disables the network forwarder
   //!
   //! This method disables the network forwarder by unregistering all message
   //! handlers. When disabled, the forwarder will not process incoming control
   //! messages or forward outgoing messages.
   virtual void disable();
 
   //! \brief Starts forwarding messages of the specified type
   //! \param messageType The type of messages to forward
   //!
   //! This method registers a handler for messages of the specified type
   //! to forward them over the network. Messages of this type will be
   //! bundled and sent when flush() is called.
   virtual void forwardEvents(const std::string& messageType);
 
   //! \brief Stops forwarding messages of the specified type
   //! \param messageType The type of messages to stop forwarding
   //!
   //! This method unregisters the handler for messages of the specified type,
   //! stopping their forwarding over the network.
   virtual void stopForwardingEvents(const std::string& messageType);
 
   //! \brief Sets the application name for this network forwarder
   //! \param applicationName The name to set for this application instance
   //!
   //! This method sets the application name used to filter incoming forwarding
   //! request messages. Only requests targeting this application name will be processed.
   virtual void setApplicationName(const std::string& applicationName);
 
   //! \brief Gets the current application name
   //! \return The current application name
   //!
   //! Returns the application name previously set with setApplicationName().
   virtual std::string applicationName();
 
   //! \brief Gets the maximum size of a message bundle
   //! \return Maximum bundle size in bytes
   //!
   //! This static method returns the maximum size of a message bundle,
   //! which is calculated to fit within a single UDP packet including headers.
   static int maxBundleSize();
 
protected:
   //! \brief Sends a message through the network
   //! \param msg Pointer to the message to send
   //! \return Message processing result (HANDLED or NOT_HANDLED)
   //!
   //! This method bundles the message for efficient network transmission. If the
   //! message was not previously forwarded (originatingApplicationId is 0), it is
   //! added to an appropriate message bundle and tagged with this forwarder's ID.
   //! The actual transmission occurs when flush() is called.
   //!
   //! Derived classes may override this method to implement custom message handling.
   virtual makVre::DtVreMessageResult netSendMessage(makVre::DtVreMessage* msg);
 
   //! \brief Handles ForwardMessage control messages
   //! \param msg Pointer to the received message
   //! \return Message processing result (HANDLED)
   //!
   //! This method processes ForwardMessage control messages, which request
   //! forwarding of a specific message type. It calls forwardEvents() with
   //! the specified message type.
   virtual makVre::DtVreMessageResult handleForwardMessage(makVre::DtVreMessage* msg);
 
   //! \brief Handles StopForwardMessage control messages
   //! \param msg Pointer to the received message
   //! \return Message processing result (HANDLED)
   //!
   //! This method processes StopForwardMessage control messages, which request
   //! stopping forwarding of a specific message type. It calls stopForwardingEvents()
   //! with the specified message type.
   virtual makVre::DtVreMessageResult handleStopForwardMessage(makVre::DtVreMessage* msg);
 
   //! \brief Handles RequestForwardMessage control messages
   //! \param msg Pointer to the received message
   //! \return Message processing result (HANDLED)
   //!
   //! This method processes RequestForwardMessage control messages, which request
   //! forwarding of a specific message type from a specific host. If the request
   //! is for this host (matching applicationName), it calls forwardEvents().
   virtual makVre::DtVreMessageResult handleRequestForwardMessage(makVre::DtVreMessage* msg);
 
   //! \brief Handles RequestStopForwardMessage control messages
   //! \param msg Pointer to the received message
   //! \return Message processing result (HANDLED)
   //!
   //! This method processes RequestStopForwardMessage control messages, which request
   //! stopping forwarding of a specific message type from a specific host. If the request
   //! is for this host (matching applicationName), it calls stopForwardingEvents().
   virtual makVre::DtVreMessageResult handleRequestStopForwardMessage(makVre::DtVreMessage* msg);
 
   //! \brief Pointer to the message factory for creating messages from raw data
   DtVreMessageFactory* myMessageFactory;
 
   //! \brief Unique identifier for this network forwarder instance
   //!
   //! This ID is used to tag outgoing messages to prevent processing loops
   //! when messages are received from the network.
   UInt64 myId;
 
   //! \brief Vector of message bundles for outgoing messages
   //!
   //! Messages are accumulated in these bundles until flush() is called.
   //! New bundles are created as needed when existing ones are full.
   std::vector<DtVreMessageBundle*> myMessageBundles;
 
   //! \brief Application name for filtering forwarding request messages
   //!
   //! Only forwarding requests targeting this application name will be processed.
   std::string myApplicationName;
};
 
} // namespace makVre