vreMessageFactory.h

Go to the documentation of this file.

/*********************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*********************************************************************************/
 
#pragma once
 
//! \file vreMessageFactory.h
//! \ingroup makEvent
//! \brief Defines a message factory for creating VREngage messages from serialized data
//!
//! This file contains the DtVreMessageFactory class which implements the factory pattern
//! for creating DtVreMessage objects from serialized byte arrays. It maintains a registry
//! of message types and their corresponding decoder functions, enabling dynamic message
//! creation based on the message type encoded in the data.
 
#include "vreMessageManager/export.h"
 
#include <map>
 
namespace makVre
{
 
class DtVreMessage;
class DtVreMessageId;
 
//! \brief Function pointer type for message decoder functions
//! \param bytes Pointer to the buffer containing the serialized message
//! \param length Length of the buffer in bytes
//! \return Pointer to a newly created message object, or nullptr if decoding fails
//!
//! This typedef defines the signature for message decoder functions. Each message
//! class must provide a static decode function with this signature to be used
//! by the message factory for creating messages from serialized data.
using Decoder = DtVreMessage* (*)(char* bytes, int length);
 
//! \brief Factory for creating VREngage messages from serialized data
//!
//! This class implements the factory pattern for creating DtVreMessage objects
//! from serialized byte arrays. It maintains a registry of message types and their
//! corresponding decoder functions, enabling dynamic message creation based on the
//! message type encoded in the data.
//!
//! The factory comes pre-registered with decoders for system messages like
//! ForwardMessage and StopForwardMessage. Additional message types can be
//! registered using the registerMessage() template method.
class MESSAGEMANAGER_DLL DtVreMessageFactory
{
public:
   //! \brief Constructor
   //!
   //! Initializes a new message factory and registers default system messages
   //! by calling installDefaultMessages().
   DtVreMessageFactory();
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the message factory.
   virtual ~DtVreMessageFactory();
 
   //! \brief Creates a message object from serialized data
   //! \param bytes Pointer to the buffer containing the serialized message
   //! \param length Length of the buffer in bytes
   //! \return Pointer to a newly created message object, or nullptr if creation fails
   //!
   //! This method deserializes the message header to determine the message type,
   //! looks up the appropriate decoder function in the registry, and calls that
   //! function to create the message object. It returns nullptr if no decoder is
   //! found for the message type or if an error occurs during decoding.
   virtual DtVreMessage* create(char* bytes, int length);
 
   //! \brief Registers a message type with the factory
   //! \tparam MSG Message class type to register
   //!
   //! This template method registers a message class with the factory by
   //! retrieving its ID and decode function. The message class must provide:
   //! - A static theId() method that returns the message's DtVreMessageId
   //! - A static decode() method with the Decoder signature
   //!
   //! Example usage:
   //! \code
   //! factory.registerMessage<MyCustomMessage>();
   //! \endcode
   template <typename MSG>
   void registerMessage()
   {
      registerCreator(MSG::theId(), &MSG::decode);
   }
 
   //! \brief Clears all registered message decoders
   //!
   //! This method removes all registered message types and their decoders
   //! from the factory. After calling this method, the factory will not be able
   //! to create any messages until new ones are registered.
   virtual void clear();
 
protected:
   //! \brief Registers a message decoder with the factory
   //! \param id Message ID object identifying the message type
   //! \param decoder Function pointer to the message's decode function
   //!
   //! This method registers a decoder function for a specific message type
   //! identified by its ID. If a decoder is already registered for the same
   //! message type hash, it will log a warning if the new decoder is different
   //! from the existing one, and then replace the existing decoder.
   virtual void registerCreator(const DtVreMessageId& id, Decoder decoder);
 
   //! \brief Installs default system message decoders
   //!
   //! This method registers decoders for the built-in system messages like
   //! ForwardMessage, StopForwardMessage, RequestForwardMessage, and
   //! RequestStopForwardMessage. It is called by the constructor.
   virtual void installDefaultMessages();
 
   //! \brief Type definition for the map of message type hashes to decoder functions
   using DecoderMap = std::map<unsigned int, Decoder>;
 
   //! \brief Map of message type hashes to their corresponding decoder functions
   //!
   //! This map stores the registered decoder functions indexed by the hash value
   //! of the message type. It is used by the create() method to look up the
   //! appropriate decoder function for a given message type.
   DecoderMap myCreatorMap;
};
 
} // namespace makVre