extendedStateConnector.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file extendedStateConnector.h
//! \brief Defines the DtExtendedStateConnector class for extended entity state handling
//!
//! This connector provides access to extended state properties of entities in the
//! simulation, supporting various data types and value retrieval mechanisms.
 
#pragma once
 
#include "export.h"
 
#include "vrePlayerStationConnector/simEventConnector.h"
#include "vreMessageManager/vreMessage.h"
 
#include <string>
#include <map>
#include <memory>
 
//! \brief Forward declaration of the reflected extended entity list class
class DtReflectedExtEntityList;
 
//! \brief Forward declaration of the reflected extended entity class
class DtReflectedExtEntity;
 
namespace makVre
{
//! \brief Connector for handling extended state properties of simulation entities
//!
//! DtExtendedStateConnector manages access to extended state properties of entities
//! in the simulation. It provides mechanisms to request specific property values,
//! monitor entity states, and convert between different data types. The connector
//! supports bool, int, float, string, and more complex types like ammo clip maps.
class VRL_DLL DtExtendedStateConnector : public DT_PROTOCOL_NAMESPACE::DtSimEventConnector
{
public:
   //! \brief Default constructor
   //!
   //! Initializes member variables with default values
   DtExtendedStateConnector();
 
   //! \brief Virtual destructor
   virtual ~DtExtendedStateConnector() override;
 
   //! \brief Installs the extended state connector with the application and connection
   //! \param app Pointer to the player station application
   //! \param connection Pointer to the protocol-specific VR-Link connection
   //!
   //! Registers message handlers for extended state requests and initialization,
   //! and retrieves the reflected extended entity list
   virtual void install(
      DtPlayerStationApp* app, makVrv::DT_PROTOCOL_NAMESPACE::DtVrlinkConnection* connection) override;
 
   //! \brief Performs periodic processing of entity state updates
   //!
   //! For monitored entities, checks and sends updates for registered state properties
   virtual void tick() override;
 
   //! \brief Shuts down the extended state connector
   //!
   //! Removes message handlers for extended state requests and initialization
   virtual void shutdown() override;
 
protected:
   //! \brief Handles requests for extended state properties
   //! \param msg Pointer to the extended state request message
   //! \return Message result indicating how the message was handled
   //!
   //! Processes ExtendedStateRequestMessage by finding the requested entity and
   //! sending the requested state property or extended data
   virtual DtVreMessageResult handleExtendedRequest(DtVreMessage* msg);
 
   //! \brief Handles initialization of extended state monitoring
   //! \param msg Pointer to the extended state monitor initialization message
   //! \return Message result indicating how the message was handled
   //!
   //! Processes ExtendedStateMonitorInitMessage by setting up tracking for
   //! the requested entity and state properties
   virtual DtVreMessageResult handleExtendedInit(DtVreMessage* msg);
 
   //! \brief Finds an extended entity by its identifier
   //! \param entityId The entity identifier to look up
   //! \return Pointer to the found extended entity, or nullptr if not found
   //!
   //! Searches the reflected extended entity list for an entity with the given ID
   virtual DtReflectedExtEntity* findEntity(DtEntityIdentifier entityId);
 
   //! \brief Sends an attribute message with a specific value type
   //! \tparam ValueType The type of the attribute value
   //! \tparam MessageType The type of message to create and send
   //! \param name The name of the attribute
   //! \param value The value of the attribute
   //! \param entityId The entity identifier to associate with the message
   //!
   //! Creates and queues a message containing the attribute name, value, and entity ID
   template <typename ValueType, typename MessageType>
   void sendAttributeMessage(const std::string& name, ValueType value, const DtEntityIdentifier& entityId);
 
   //! \brief Sends a state property message with type conversion
   //! \tparam RwType The reader/writer type for the property
   //! \tparam ValueType The target value type
   //! \tparam MessageType The type of message to create and send
   //! \param entity Pointer to the entity containing the property
   //! \param name The name of the state property
   //! \return True if the property was found and sent, false otherwise
   //!
   //! Looks up a property of the specified reader/writer type, converts it to the
   //! target value type, and sends it in a message of the specified message type
   template <typename RwType, typename ValueType, typename MessageType>
   bool sendStatePropertyMessage(DtReflectedExtEntity* entity, const std::string& name);
 
   //! \brief Sends an extended data message for a specific entity
   //! \param entity Pointer to the entity containing the extended data
   //! \param name The name of the extended data property
   //! \param type The type of the extended data property
   //!
   //! Creates and sends a message containing extended data from the entity
   virtual void sendExtendedDataMessage(DtReflectedExtEntity* entity, const std::string& name, const std::string& type);
 
   //! \brief Sends a state property message with type dispatching
   //! \param entity Pointer to the entity containing the property
   //! \param name The name of the state property
   //! \param type The type of the state property ("bool", "int", "float", "string", "ammoClipMap")
   //! \return True if the property was found and sent, false otherwise
   //!
   //! Dispatches to the appropriate typed sendStatePropertyMessage based on the type string
   virtual bool sendStatePropertyMessage(
      DtReflectedExtEntity* entity, const std::string& name, const std::string& type);
 
   //! \brief Logs a warning about missing extended state data
   //! \param name The name of the missing state property
   //! \param type The type of the missing state property
   //!
   //! Logs a warning message the first time a specific state property is not found.
   //! Subsequent missing properties with the same name and type won't generate
   //! additional log messages to prevent log spam.
   void logMissingStateProperty(const std::string& name, const std::string& type);
 
   //! \brief Mapping of state names to their types
   std::map<std::string, std::string> myNameTypeMap;
 
   //! \brief Mapping of property names to their types
   std::map<std::string, std::string> myPropertyTypeMap;
 
   //! \brief Entity identifier for the monitored entity
   DtEntityIdentifier myEntityId;
 
   //! \brief Global object designator for the monitored entity
   DtGlobalObjectDesignator myGlobalId;
 
   //! \brief Pointer to the reflected extended entity list
   DtReflectedExtEntityList* myRel;
 
   //! \brief Cache for extended state data that is missing
   //!
   //! Used to limit the amount of warning messages put into the log by
   //! tracking which properties have already had warnings issued
   std::set<std::string> myMissingStateProperties;
};
} // namespace makVre